home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 23 / AACD 23.iso / AACD / Programming / ExtraLib / Docs / Extra.DOC < prev    next >
Encoding:
Text File  |  2001-05-01  |  94.4 KB  |  1,761 lines
  1. ExtractDocs Version 1.0
  2. Copyright © Roland Heyder 1994
  3.  
  4. TABLE OF CONTENTS
  5. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  6. Legal-ReadMe
  7. Haftung
  8. Hinweise
  9. Details
  10. Danksagung
  11. extra.library / BAMCheckSum()           (OFFSET -42) V1.323
  12. extra.library / BootBlockSum()          (OFFSET -48) V1.323
  13. extra.library / DiskBlockSum()          (OFFSET -54) V1.323
  14. extra.library / OpenBuf()               (OFFSET -60) V1.323
  15. extra.library / v2_OpenBuf()            (OFFSET -300) V2.062
  16. extra.library / CloseBuf()              (OFFSET -66) V1.323
  17. extra.library / FileToBuf()             (OFFSET -72) V1.323
  18. extra.library / v2_FileToBuf()          (OFFSET -306) V2.062
  19. extra.library / BufToFile()             (OFFSET -78) V1.323
  20. extra.library / ClearBuf()              (OFFSET -84) V1.323
  21. extra.library / DuplicateBuf()          (OFFSET -90) V1.323
  22. extra.library / v2_DuplicateBuf()       (OFFSET -312) V2.062
  23. extra.library / BufInfo()               (OFFSET -96) V1.323
  24. extra.library / SeekBuf()               (OFFSET -102) V1.323
  25. extra.library / Store()                 (OFFSET -108) V1.323
  26. extra.library / InsertBuf()             (OFFSET -114) V1.323
  27. extra.library / InsertFile()            (OFFSET -120) V1.323
  28. extra.library / Replace()               (OFFSET -126) V1.323
  29. extra.library / Get()                   (OFFSET -132) V1.323
  30. extra.library / Clear()                 (OFFSET -138) V1.323
  31. extra.library / FindData()              (OFFSET -144) V1.323
  32. extra.library / FindNext()              (OFFSET -150) V1.323
  33. extra.library / FindPrev()              (OFFSET -156) V1.323
  34. extra.library / FreeFinds()             (OFFSET -162) V1.323
  35. extra.library / SetBookmark()           (OFFSET -168) V1.323
  36. extra.library / GotoBookmark()          (OFFSET -174) V1.323
  37. extra.library / FindString()            (OFFSET -180) V1.323
  38. extra.library / GetLength()             (OFFSET -186) V1.323
  39. extra.library / LastError()             (OFFSET -192) V1.323
  40. extra.library / LongToString()          (OFFSET -198) V1.323
  41. extra.library / StringToLong()          (OFFSET -204) V1.323
  42. extra.library / PackByteRun1()          (OFFSET -210) V1.323
  43. extra.library / UnpackByteRun1()        (OFFSET -216) V1.323
  44. extra.library / PrintIoError()          (OFFSET -222) V1.323
  45. extra.library / FlipCase()              (OFFSET -228) V1.323
  46. extra.library / CmpMem()                (OFFSET -234) V1.323
  47. extra.library / CopyMemI()              (OFFSET -240) V1.323
  48. extra.library / FillMem()               (OFFSET -246) V1.323
  49. extra.library / GetMem()                (OFFSET -252) V1.323
  50. extra.library / UnGetMem()              (OFFSET -258) V1.323
  51. extra.library / OutlineOff()            (OFFSET -264) V1.323
  52. extra.library / OutlineOn()             (OFFSET -270) V1.323
  53. extra.library / SetOPen()               (OFFSET -276) V1.323
  54. extra.library / SpecText()              (OFFSET -282) V1.323
  55. extra.library / SpecTextPrefs()         (OFFSET -288) V1.323
  56. extra.library / ShowMsg()               (OFFSET -294) V1.323
  57. extra.library / SMCOLOR()
  58. extra.library / SMTEXTP()
  59. extra.library / SMTEXT()
  60. lvo / Lib-Call-Macro
  61.  
  62.  
  63. ;*** Legal-ReadMe ***
  64. ;============================================================================
  65. ; ___________________________________________________________________________
  66. ; |*************************************************************************|
  67. ; |*|¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯|*|¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯|*|
  68. ; |*|               |*|  $Id: extra.library (28.04.01)                    |*|
  69. ; |*| ###### ###### |*|  RhoSigma Source based on NDK 3.1 Includes 40.15  |*|
  70. ; |*| ##  ## ##   # |*| _________________________________________________ |*|
  71. ; |*| ##  ##  ##    |*|                                                   |*|
  72. ; |*| ######   ##   |*|  Shared library with OS supporting functions      |*|
  73. ; |*| ##      ##    |*|                                                   |*|
  74. ; |*| ##     ##   # |*| ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ |*|
  75. ; |*| ##     ###### |*|  Copyright © 1998-2001 RhoSigma, Roland Heyder    |*|
  76. ; |*|               |*|  All Rights Reserved.                             |*|
  77. ; |*|_______________|*|___________________________________________________|*|
  78. ; |*************************************************************************|
  79. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  80. ; Die folgenden Worte beziehen sich auf das Projekt »extra.library«. Dieses
  81. ; Projekt beinhaltet folgende Dateien:
  82. ;
  83. ; Verzeichnis: Extra
  84. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  85. ;  ReadMe          - was Sie gerade lesen
  86. ;  Install         - kopiert die Library ins LIBS:-Verzeichnis
  87. ;
  88. ; Verzeichnis: Extra/libs
  89. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  90. ;  extra.lib_ocs     - der Programmcode (eine Shared-Library) OCS/ECS/AGA
  91. ;  extra.lib_cgx     - die CyberGraphX-fähige Variante der Library
  92. ;
  93. ; Verzeichnis: Extra/include/rhosigma
  94. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  95. ;  extra_lib.fd    - Funktions- und Parameterdefinitionen
  96. ;
  97. ;  extradefs.i     - Definition von Konstanten (Assembler)
  98. ;  extra_lib.i     - die Library-Vector-Offsets (Assembler)
  99. ;
  100. ;  extradefs.h     - Definition von Konstanten (ANSI-C/C++)
  101. ;  extra_lib.h     - die amicall/libcall-Pragmas (ANSI-C/C++)
  102. ;  extra_protos.h  - die Prototypen der Funktionen (ANSI-C/C++)
  103. ;
  104. ;  extra.bh        - Header-File für div. BASICs (HBC-Compiler)
  105. ;  extra.bc        - Constants-File für div. BASICs (HBC-Compiler)
  106. ;  extra.bmap      - Hilfsdatei für div. BASICs
  107. ;
  108. ;  settings.i      - weitere globale Definitionen (Assembler)
  109. ;  settings.h      - weitere globale Definitionen (ANSI-C/C++)
  110. ;  settings.bc     - weitere globale Definitionen für BASIC
  111. ;
  112. ;  rhosigma.c      - Source-Datei mit zusätzlichen Hilfs-Funktionen
  113. ;  rhosigma.h      - Prototypen & Defines für rhosigma.c (ANSI-C/C++)
  114. ;
  115. ; Verzeichnis: Extra/Docs
  116. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  117. ;  Extra.DOC       - Dokumentation extra.library (ASCII-Datei)
  118. ;  ExtraV34.guide  - Dokumentation extra.library (AmigaGuide® für OS 1.3+)
  119. ;  ExtraV39.guide  - Dokumentation extra.library (AmigaGuide® für OS 3.0+)
  120. ;
  121. ; Verzeichnis: Extra/Demos
  122. ; ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  123. ;  ShowMsgDemo.ASM - Beispiel für »extradefs.i« Assembler-Macros
  124. ;  ShowMsgDemo.C   - Beispiel für »extradefs.h« Macros & Funktionen (ANSI-C/C++)
  125. ;  ShowMsgDemo.BAS - Beispiel für »extra.bc« BASIC-Funktionen
  126. ;
  127. ;  AlertDemo.ASM - Beispiel für »settings.i« Assembler-Macros
  128. ;  AlertDemo.C   - Beispiel für »settings.h« Macros & Funktionen (ANSI-C/C++)
  129. ;  AlertDemo.BAS - Beispiel für »settings.bc« BASIC-Funktionen
  130. ;
  131. ;  Das Projekt »extra.library« ist als SHAREWARE konzipiert und alle oben ge-
  132. ; nannten Dateien werden im Rahmen der Demoversion zur Verfügung gestellt.
  133. ;
  134. ;  Sie dürfen das Original-Archiv bzw. -Verzeichnis der Demoversion so oft Sie
  135. ; wollen kopieren und weitergeben, dabei dürfen alle Wege benutzt werden, die
  136. ; eine weitestmögliche Verbreitung garantieren.
  137. ;  Bei Vertrieb zusammen mit kommerzieller Software ist jedoch ausdrücklich
  138. ; darauf hinzuweisen, daß der Autor der »extra.library« kein Geld aus dem
  139. ; Verkauf dieser Software erhalten hat, und somit weiterhin die Notwendigkeit
  140. ; zur Registrierung der »extra.library« direkt beim Autor bestehen bleibt.
  141. ;
  142. ;  Wenn Sie sich registrieren lassen, dann erhalten Sie von mir so schnell
  143. ; wie möglich eine aktuelle Vollversion ohne Einschränkungen. Außerdem liegen
  144. ; der Vollversion noch einige andere Kleinigkeiten bei.
  145. ;
  146. ;  Die Demoversion enthält, außer daß das Expunge-System (bei Speichermangel)
  147. ; nicht funktioniert, keine weiteren Einschränkungen im Funktionsumfang. Sie
  148. ; haben also die Möglichkeit alle Funktionen uneingeschränkt zu testen, bevor
  149. ; Sie sich entscheiden sich registrieren zu lassen. Es werden jedoch Nerv-
  150. ; Alerts bei jedem Öffnen und Schließen der Library ausgegeben, und es gibt
  151. ; eine sich ca. alle 10 Minuten wiederholende 2-minütige Systemblockade. Da-
  152. ; bei wird das System auf die Art und Weise lahmgelegt, daß weder Eingaben
  153. ; getätigt werden können, noch irgendwelche anderen interaktiven Vorgänge
  154. ; stattfinden können. Zu Beginn und Ende der Blockade wird jeweils ein Alert
  155. ; ausgegeben, damit Sie nicht etwa denken, Ihr Rechner habe sich still und
  156. ; leise »verabschiedet«.
  157. ;
  158. ;  Die Funktionen der »normalen« Library sind alle schon auf einer Minimal-
  159. ; Konfiguration lauffähig, d.h. ab Kickstart-Release 1.2 (V33+), 68000er CPU
  160. ; und 512KB RAM.
  161. ;  Die »CyberGraphX-Version« der Library benötigt jedoch als minimum mindest-
  162. ; ens Kickstart 2.0 (V36+). Des weiteren sollte die »cybergraphics.library« v40+
  163. ; zur Verfügung stehen, was aber nicht zwingend erforderlich ist. Wenn die
  164. ; CGX-Version der »extra.library« also auf einem System ohne installiertem CGX
  165. ; verwendet wird, dann wird dies erkannt, und auf die dementsprechend verfüg-
  166. ; baren Custom-Chips zurückgegriffen.
  167. ;
  168. ;  Um sich registrieren zu lassen, senden Sie bitte DM 15,- (oder mehr) bzw.
  169. ; den entsprechenden Gegenwert in anderen Währungen (es gilt der Sorten-
  170. ; Abschlußkurs des vorangegangenen Börsen-Tages) an untenstehende Adresse
  171. ; (Bargeld, Euro- oder Verrechnungsscheck). Bitte vergessen Sie nicht Ihren
  172. ; Namen und Ihre vollständige Adresse. Haben Sie einen Fehler entdeckt, oder
  173. ; haben Sie Erweiterungsvorschläge ?? - Auch in diesen Fällen gilt folgende
  174. ; Adresse:
  175. ;
  176. ;                             Roland Heyder
  177. ;                             Oberstadt 44
  178. ;                             38877 Benneckenstein
  179. ;                             Germany
  180. ;
  181. ;                      PHONE: +49 (0)39457 / 2540
  182. ;
  183. ;                     E-MAIL: rhosigma@crosswinds.net
  184. ;
  185. ; P.S. - Disk und Versandkosten sind bereits in der Share-Gebür enthalten !!
  186. ;        Wenn Sie die Vollversion via E-mail erhalten wollen, dann stellen
  187. ;        Sie bitte unbedingt sicher, daß Sie Ihre E-mail-Adresse richtig an-
  188. ;        geben (Groß-/Kleinschreibung, Leerstellen, Punkte etc.). Bei E-mail-
  189. ;        Versandt reduziert sich außerdem die Share-Gebür auf DM 10,- da die
  190. ;        Disk- u. Portokosten entfallen.
  191. ;
  192. ; Nun viel Spaß mit der »extra.library« und vielen Dank für Ihr Interesse.
  193. ;============================================================================
  194.  
  195. ;*** Haftung ***
  196. ;============================================================================
  197. ;  Hiermit lehne ich ausdrücklich jegliche Haftung bzw. Verantwortung für
  198. ; Konsequenzen aller Art, die aus dem Gebrauch des Projektes »extra.library«
  199. ; resultieren, strikt ab.
  200. ;
  201. ;  Die »extra.library« wird Ihnen von mir so zur Verfügung gestellt, wie
  202. ; Sie sie vorgefunden haben. Das heißt, ich garantiere nicht, daß eventuelle
  203. ; Programmierfehler behoben werden, daß neue Versionen erscheinen, oder daß
  204. ; Sie Hilfe erhalten, falls bei Ihnen ein Fehler auftritt.
  205. ;
  206. ;  Obwohl die »extra.library« gründlich auf »Herz und Nieren« getestet wur-
  207. ; de, kann ich die Möglichkeit nicht ausschließen, daß die Library:
  208. ;  - aus irgendwelchen Gründen nicht kompatibel zu Ihrem Rechner ist
  209. ;  - Fehler enthält, die nur auf Ihrem Rechner auftreten
  210. ;  - auf Ihrem Rechner nicht die erwarteten Resultate liefert
  211. ;
  212. ;  Es liegt ausschließlich in Ihrer Verantwortung, alle notwendigen Sicher-
  213. ; heitsmaßnahmen zu treffen, um sich vor jeglichen schädlichen Auswirkungen
  214. ; bei der Nutzung der »extra.library« zu schützen.
  215. ;============================================================================
  216.  
  217. ;*** Hinweise ***
  218. ;============================================================================
  219. ; - Sollten Sie im folgenden Text auf die Zeichenkombination »(+0)« treffen,
  220. ;   dann ist damit gemeint, daß der angegebene Parameter mit einem 0-Byte
  221. ;   abgeschlossen werden muß (z.B. Dateinamen etc.).
  222. ;    Wenn es sich jedoch um das Ergebnis einer Funktion handelt, dann können
  223. ;   Sie bei dieser Angabe davon ausgehen, daß dieses 0-terminiert ist.
  224. ;
  225. ; - Parameter des Typs BOOL sind normaler Weise TRUE bzw. FALSE. Ich habe
  226. ;   jedoch noch 3 neue Werte »erfunden« (UPPER/EQUAL/LOWER), deren Definition
  227. ;   Sie im mitgelieferten Includefile »settings.i« finden.
  228. ;
  229. ; - Für alle Parameter, die mit »An!« bzw. »Dn!« angegeben sind, tragen Sie
  230. ;   die volle Verantwortung, daß es sich wirklich um die von der Funktion
  231. ;   benötigten Daten handelt. Alle anderen Parameter werden intern überprüft.
  232. ;
  233. ; - Bei Funktionen, bei denen das Ergebnis mit »D0*« angegeben ist, handelt
  234. ;   es sich um Ergebnistestende Funktionen (s.a. Abschnitt »Details«).
  235. ;
  236. ; ACHTUNG: Die normalen Regeln beim Umgang mit Shared-Libraries sollten
  237. ; ¯¯¯¯¯¯¯¯ immer beachtet werden. Das heißt vor allem, daß Sie die Library
  238. ;          vor der Benutzung öffnen, und sich den Basiszeiger nicht etwa
  239. ;          aus der ExecBase.LibList holen. Einige Funktionen reagieren mit
  240. ;          dem DeadEnd-Alert »EL_Trespassed« (s. extradefs.i), wenn Sie den
  241. ;          Zugriff nicht vorher angemeldet haben.
  242. ;
  243. ; Zum Ende möchte ich noch sagen, daß Sie hier eine recht umfangreiche Doku-
  244. ; mentation vor sich haben, und wo viel Text ist, da sind sicher auch viele
  245. ; Fehler. Darum möchte ich Sie bitten, daß wenn Sie mich kontaktieren, dann
  246. ; nicht nur um mir zu sagen, daß ich hier oder dort einen Schreibfehler ge-
  247. ; macht habe !!
  248. ;============================================================================
  249.  
  250. ;*** Details ***
  251. ;============================================================================
  252. ; Hier noch einige technische Hintergrundinformationen für Interessierte.
  253. ;----------------------------------------------------------------------------
  254. ; - Die Library ist kein Linkerprodukt aus Hochsprachen-Modulen, sondern
  255. ;   zu 100% in Assembler (DevPac 3.04) verfasst.
  256. ;
  257. ; - Keine Scratch-Register: bei allen Funktionen bleiben sämtliche Register-
  258. ;   inhalte, außer der des Rückgaberegisters D0, erhalten (es sei denn, daß
  259. ;   die Funktion kein Ergebnis liefert, dann bleibt D0 auch erhalten).
  260. ;
  261. ; - Alle Funktionen, bei denen beim Ergebnis »D0*« angegeben ist, testen das
  262. ;   Ergebnis unmittelbar vorm Return auf NULL (tst.l d0).
  263. ;    Da der Returnbefehl (rts) die Flags nicht verändert, können Assembler-
  264. ;   programmierer nach dem Funktionsaufruf sofort den Condition-Code auswerten,
  265. ;   wenn die Funktion zurückkehrt, und brauchen nicht noch selbst einen Test-
  266. ;   befehl zu programmieren.
  267. ;
  268. ; - Zum Teil hochoptimierter Code (auch auf 68000er CPU), vor allem bei zeit-
  269. ;   kritischen Funktionen.
  270. ;
  271. ; - Effektive Verwaltung der intern benötigten Speicherresourcen, wodurch
  272. ;   die meisten Funktionen auch bei stark fragmentierten Speicherlisten noch
  273. ;   immer lauffähig sind.
  274. ;
  275. ; - Das dynamische Puffersystem (DBS) sollte allen Programmierern von Editoren,
  276. ;   Datei-Managern o.ä. ein willkommenes Hilfsmittel sein. Der Speicher wird,
  277. ;   wie der Name schon sagt, dynamisch verwaltet, d.h. wie die RAM DISK, so
  278. ;   wird auch jeder Puffer in seiner Größe der gerade zu verwaltenden Daten-
  279. ;   menge (bis auf 4KB) genau angepasst.
  280. ;============================================================================
  281.  
  282. ;*** Danksagung ***
  283. ;============================================================================
  284. ; Vielen Dank schon jetzt an alle die, die sich trotz der allgemein schlech-
  285. ; ten Zahlungsmoral bei derartigen Produkten registrieren lassen werden. Sie
  286. ; motivieren mich dadurch, die Library weiter zu pflegen und zu erweitern.
  287. ;============================================================================
  288.  
  289. ;*** extra.library / BAMCheckSum()           (OFFSET -42) V1.323 ***
  290. ;============================================================================
  291. ; Diese Funktion berechnet die Checksumme eines Bitmap-Blocks innerhalb
  292. ; eines der gängigen Amiga-FileSysteme (DOS/0 - DOS/5), welches eine Block-
  293. ; größe von 512 Bytes verwendet (z.B. normale Disketten).
  294. ;----------------------------------------------------------------------------
  295. ; Synopsis:    success = BAMCheckSum (Block)
  296. ;                D0*                   A0!
  297. ;
  298. ; Eingaben:    A0 --> APTR auf die Startadresse des Blocks (gerade Adresse,
  299. ;                          sonst folgt Fehler)
  300. ;
  301. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  302. ;                          - FALSE, wenn Startadresse ungerade war
  303. ;
  304. ; Bemerkung:   Die Summe wird gleich ordnungsgemäß in den Block geschrieben,
  305. ;              so daß er anschließend sofort gespeichert werden kann.
  306. ;
  307. ; Siehe auch:  »BootBlockSum()«, »DiskBlockSum()«
  308. ;============================================================================
  309.  
  310. ;*** extra.library / BootBlockSum()          (OFFSET -48) V1.323 ***
  311. ;============================================================================
  312. ; Diese Funktion berechnet die Checksumme eines Boot-Blocks innerhalb eines
  313. ; der gängigen Amiga-FileSysteme (DOS/0 - DOS/5), welches eine Blockgröße
  314. ; von 512 Bytes verwendet (z.B. normale Disketten).
  315. ;----------------------------------------------------------------------------
  316. ; Synopsis:    success = BootBlockSum (Block)
  317. ;                D0*                    A0!
  318. ;
  319. ; Eingaben:    A0 --> APTR auf die Startadresse des Blocks (gerade Adresse,
  320. ;                          sonst folgt Fehler)
  321. ;
  322. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  323. ;                          - FALSE, wenn Startadresse ungerade war
  324. ;
  325. ; Bemerkung:   Beachten Sie, daß den Boot-Block eigentlich zwei hinterein-
  326. ;              ander auf der Diskette liegende Blöcke darstellen (Block 0-1).
  327. ;              Auch bei der Berechnung müssen beide Blöcke unmittelbar hin-
  328. ;              tereinander im Speicher liegen.
  329. ;              Die Summe wird gleich ordnungsgemäß in den Block geschrie-
  330. ;              ben, so daß er anschließend sofort gespeichert werden kann.
  331. ;
  332. ; Siehe auch:  »BAMCheckSum()«, »DiskBlockSum()«
  333. ;============================================================================
  334.  
  335. ;*** extra.library / DiskBlockSum()          (OFFSET -54) V1.323 ***
  336. ;============================================================================
  337. ; Diese Funktion berechnet die Checksumme eines beliebigen Blocks innerhalb
  338. ; eines der gängigen Amiga-FileSysteme (DOS/0 - DOS/5), welches eine Block-
  339. ; größe von 512 Bytes verwendet (z.B. normale Disketten), der KEINEN Boot-Block
  340. ; und KEINEN Bitmap-Block darstellt.
  341. ;----------------------------------------------------------------------------
  342. ; Synopsis:    success = DiskBlockSum (Block)
  343. ;                D0*                    A0!
  344. ;
  345. ; Eingaben:    A0 --> APTR auf die Startadresse des Blocks (gerade Adresse,
  346. ;                          sonst folgt Fehler)
  347. ;
  348. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  349. ;                          - FALSE, wenn Startadresse ungerade war
  350. ;
  351. ; Bemerkung:   Die Summe wird gleich ordnungsgemäß in den Block geschrieben,
  352. ;              so daß er anschließend sofort gespeichert werden kann.
  353. ;
  354. ;   ACHTUNG:   Handelt es sich um ein FastFile-System (DOS/1, DOS/3, DOS/5),
  355. ;   ¯¯¯¯¯¯¯¯   dann darf diese Funktion NICHT auf Data-Blöcke angewendet
  356. ;              werden, da diese beim FFS keine Checksummen enthalten.
  357. ;              Nichtbeachtung führt zu Datenverlust, für den ich KEINERLEI
  358. ;              HAFTUNG übernehme !!
  359. ;
  360. ; Siehe auch:  »BAMCheckSum()«, »BootBlockSum()«
  361. ;============================================================================
  362.  
  363. ;*** extra.library / OpenBuf()               (OFFSET -60) V1.323 ***
  364. ;============================================================================
  365. ; Diese Funktion baut einen neuen dynamischen Puffer auf, und führt alle
  366. ; nötigen Initialisierungen durch. Als Ergebnis erhalten Sie einen Zeiger,
  367. ; der bei allen Pufferfunktionen als Identifikation dieses Puffers dient.
  368. ;----------------------------------------------------------------------------
  369. ; Synopsis:    bufHandle = OpenBuf (VOID)
  370. ;                 D0*
  371. ;
  372. ; Ergebnis:    D0 --> APTR - auf den initialisierten BufHandle
  373. ;                          - 0-PTR, wenn Fehler (Info mit »LastError()«)
  374. ;
  375. ; Bemerkung:   Jeder geöffnete Puffer sollte, wenn er nicht mehr benötigt
  376. ;              wird, mittels »CloseBuf()« wieder geschlossen werden bzw.
  377. ;              wenigstens mittels der Funktion »ClearBuf()« auf minimalen
  378. ;              Speicherverbrauch reduziert werden.
  379. ;
  380. ;   ACHTUNG:   Wenn Sie sich Puffer mit anderen Prozessen teilen, dann liegt
  381. ;   ¯¯¯¯¯¯¯¯   es ausschließlich in Ihrer Verantwortung, Zugriffe auf diese
  382. ;              Puffer so zu koordinieren und zu sichern, daß die Prozesse im
  383. ;              Rahmen des Multitaskings nicht gleichzeitig auf die Puffer zu-
  384. ;              greifen können !! - Achten Sie immer darauf, daß jede Puffer-
  385. ;              funktion vollständig abgeschlossen wurde, bevor ein anderer
  386. ;              Prozess die nächste startet.
  387. ;
  388. ; Siehe auch:  »CloseBuf()«, »FileToBuf()«, »BufToFile()«, »ClearBuf()«,
  389. ;              »DuplicateBuf()«, »BufInfo()«
  390. ;
  391. ;----------------------------------------------------------------------------
  392. ;--- Veränderungen seit v2.062 ----------------------------------------------
  393. ;----------------------------------------------------------------------------
  394. ;
  395. ; Bemerkung:   Diese Funktion ist veraltet, bitte benutzen Sie stattdessen
  396. ;              die Funktion »v2_OpenBuf()«, welche zusätzlich die Angabe von
  397. ;              Speicher-Flags ermöglicht, um z.B. Audio- oder Grafik-Daten
  398. ;              gezielt ins CHIP-Ram zu verlagern.
  399. ;
  400. ;   ACHTUNG:   Diese Funktion hat und wird immer nur PUBLIC-Memory für den
  401. ;   ¯¯¯¯¯¯¯¯   Datenbereich verwenden, und unterliegt der durch das System
  402. ;              festgelegten Zuordnungsreihenfolge (meist FAST vor CHIP) !!
  403. ;
  404. ; Siehe auch:  »v2_FileToBuf()«, »v2_DuplicateBuf()«
  405. ;============================================================================
  406.  
  407. ;*** extra.library / v2_OpenBuf()            (OFFSET -300) V2.062 ***
  408. ;============================================================================
  409. ; Diese Funktion baut einen neuen dynamischen Puffer auf, und führt alle
  410. ; nötigen Initialisierungen durch. Dabei kann noch angegeben werden, welcher
  411. ; Speichertyp für den Datenbereich verwendet werden soll. Als Ergebnis erhalten
  412. ; Sie einen Zeiger, der bei allen weiteren Pufferfunktionen als Identifikation
  413. ; dieses Puffers dient.
  414. ;----------------------------------------------------------------------------
  415. ; Synopsis:    bufHandle = v2_OpenBuf (MemType)
  416. ;                 D0*                    D0!
  417. ;
  418. ; Eingaben:    D0 --> ULONG eine Kombination von Speicher-Flags wie sie in
  419. ;                           der Include-Datei »exec/memory.i« definiert sind.
  420. ;
  421. ; Ergebnis:    D0 --> APTR - auf den initialisierten BufHandle
  422. ;                          - 0-PTR, wenn Fehler (Info mit »LastError()«)
  423. ;
  424. ; Bemerkung:   Es gelten die gleichen Konditionen wie bei »OpenBuf()«
  425. ;
  426. ; Siehe auch:  »v2_FileToBuf()«, »v2_DuplicateBuf()«
  427. ;============================================================================
  428.  
  429. ;*** extra.library / CloseBuf()              (OFFSET -66) V1.323 ***
  430. ;============================================================================
  431. ; Diese Funktion schließt den angegebenen Puffer und gibt alle damit ver-
  432. ; bundenen Speicherresourcen an das System zurück. Nach Aufruf dieser Funk-
  433. ; tion können keine weiteren Pufferfunktionen mehr auf den angegebenen
  434. ; BufHandle ausgeführt werden.
  435. ;----------------------------------------------------------------------------
  436. ; Synopsis:    success = CloseBuf (BufHandle)
  437. ;                D0*                  A0
  438. ;
  439. ; Eingaben:    A0 --> APTR auf den zu schließenden BufHandle
  440. ;
  441. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  442. ;                          - FALSE, wenn Fehler (Info mit »LastError()«)
  443. ;
  444. ;   ACHTUNG:   Wenn ein Task die »extra.library« ENDGÜLTIG schließt (es kann
  445. ;   ¯¯¯¯¯¯¯¯   ja sein, daß mehrere Open-Aufrufe verschachtelt wurden), dann
  446. ;              werden automatisch alle noch offenen Puffer, die DIESER TASK
  447. ;              geöffnet hat (egal, mit welcher Funktion) wieder geschlossen.
  448. ;              Diese Funktion löscht automatisch die Prozessor-Caches.
  449. ;
  450. ; Siehe auch:  »OpenBuf()«, »FileToBuf()«, »BufToFile()«, »ClearBuf()«,
  451. ;              »DuplicateBuf()«, »BufInfo()«
  452. ;============================================================================
  453.  
  454. ;*** extra.library / FileToBuf()             (OFFSET -72) V1.323 ***
  455. ;============================================================================
  456. ; Diese Funktion läd die Datei mit dem angegebenen Namen in einen neuen dy-
  457. ; namischen Puffer. Es wird der fertig initialisierte BufHandle des neu an-
  458. ; gelegten Puffers zurückgegeben. Die aktuelle Cursorposition steht nach dem
  459. ; Laden auf dem Pufferanfang (Pos. 0).
  460. ;----------------------------------------------------------------------------
  461. ; Synopsis:    bufHandle = FileToBuf (FileName)
  462. ;                 D0*                   A0!
  463. ;
  464. ; Eingaben:    A0 --> STRPTR auf einen AmigaDOS-Dateinamen(+0)
  465. ;
  466. ; Ergebnis:    D0 --> APTR - auf den neu initialisierten BufHandle
  467. ;                          - 0-PTR, wenn Fehler (Info mit »LastError()«)
  468. ;
  469. ; Bemerkung:   Ein mittels dieser Funktion geöffneter Puffer wird ebenfalls
  470. ;              mit »CloseBuf()« wieder geschlossen.
  471. ;              Diese Funktion löscht automatisch die Prozessor-Caches.
  472. ;
  473. ;   ACHTUNG:   Diese Funktion darf NUR von vollwertigen DOS-Prozessen auf-
  474. ;   ¯¯¯¯¯¯¯¯   gerufen werden. Ein normaler EXEC-Task ist nicht ausreichend.
  475. ;
  476. ; Siehe auch:  »OpenBuf()«, »CloseBuf()«, »BufToFile()«, »ClearBuf()«,
  477. ;              »DuplicateBuf()«, »BufInfo()«
  478. ;
  479. ;----------------------------------------------------------------------------
  480. ;--- Veränderungen seit v2.062 ----------------------------------------------
  481. ;----------------------------------------------------------------------------
  482. ;
  483. ; Bemerkung:   Diese Funktion ist veraltet, bitte benutzen Sie stattdessen
  484. ;              die Funktion »v2_FileToBuf()«, welche zusätzlich die Angabe von
  485. ;              Speicher-Flags ermöglicht, um z.B. Audio- oder Grafik-Daten
  486. ;              gezielt ins CHIP-Ram zu laden.
  487. ;
  488. ;   ACHTUNG:   Diese Funktion hat und wird immer nur PUBLIC-Memory für den
  489. ;   ¯¯¯¯¯¯¯¯   Datenbereich verwenden, und unterliegt der durch das System
  490. ;              festgelegten Zuordnungsreihenfolge (meist FAST vor CHIP) !!
  491. ;
  492. ; Siehe auch:  »v2_OpenBuf()«, »v2_DuplicateBuf()«
  493. ;============================================================================
  494.  
  495. ;*** extra.library / v2_FileToBuf()          (OFFSET -306) V2.062 ***
  496. ;============================================================================
  497. ; Diese Funktion läd die Datei mit dem angegebenen Namen in einen neuen dy-
  498. ; namischen Puffer. Dabei kann noch angegeben werden, welcher Speichertyp für
  499. ; den Datenbereich verwendet werden soll. Es wird der fertig initialisierte
  500. ; BufHandle des neu angelegten Puffers zurückgegeben. Die aktuelle Cursorpo-
  501. ; sition steht nach dem Laden auf dem Pufferanfang (Pos. 0).
  502. ;----------------------------------------------------------------------------
  503. ; Synopsis:    bufHandle = v2_FileToBuf (FileName, MemType)
  504. ;                 D0*                      A0!       D0!
  505. ;
  506. ; Eingaben:    A0 --> STRPTR auf einen AmigaDOS-Dateinamen(+0)
  507. ;              D0 --> ULONG  eine Kombination von Speicher-Flags wie sie in
  508. ;                            der Include-Datei »exec/memory.i« definiert sind.
  509. ;
  510. ; Ergebnis:    D0 --> APTR - auf den neu initialisierten BufHandle
  511. ;                          - 0-PTR, wenn Fehler (Info mit »LastError()«)
  512. ;
  513. ; Bemerkung:   Es gelten die gleichen Konditionen wie bei »FileToBuf()«
  514. ;
  515. ; Siehe auch:  »v2_OpenBuf()«, »v2_DuplicateBuf()«
  516. ;============================================================================
  517.  
  518. ;*** extra.library / BufToFile()             (OFFSET -78) V1.323 ***
  519. ;============================================================================
  520. ; Diese Funktion schreibt den gesamten Datenbereich des durch den BufHandle
  521. ; spezifizierten Puffers in eine Datei mit dem angegebenen Namen.
  522. ;----------------------------------------------------------------------------
  523. ; Synopsis:    written = BufToFile (BufHandle, FileName)
  524. ;                D0*                   A0        A1!
  525. ;
  526. ; Eingaben:    A0 --> APTR   auf den gewünschten BufHandle
  527. ;              A1 --> STRPTR auf einen AmigaDOS-Dateinamen(+0)
  528. ;
  529. ; Ergebnis:    D0 --> LONG - Anzahl der geschriebenen Bytes
  530. ;                          - negativ, wenn Fehler (Info mit »LastError()«)
  531. ;
  532. ; Bemerkung:   Ist beim Schreiben der Datei ein Fehler aufgetreten, dann wird
  533. ;              die unvollständige (fehlerhafte) Datei gleich wieder gelöscht.
  534. ;
  535. ;   ACHTUNG:   Diese Funktion darf NUR von vollwertigen DOS-Prozessen auf-
  536. ;   ¯¯¯¯¯¯¯¯   gerufen werden. Ein normaler EXEC-Task ist nicht ausreichend.
  537. ;
  538. ; Siehe auch:  »OpenBuf()«, »CloseBuf()«, »FileToBuf()«, »ClearBuf()«,
  539. ;              »DuplicateBuf()«, »BufInfo()«
  540. ;============================================================================
  541.  
  542. ;*** extra.library / ClearBuf()              (OFFSET -84) V1.323 ***
  543. ;============================================================================
  544. ; Diese Funktion löscht den gesamten Inhalt des angegebenen Puffers, und
  545. ; reduziert dessen Speicherbedarf auf ein Minimum von 4KB. Außerdem werden,
  546. ; wenn vorhanden, auch die internen Kopien aller Such-Daten wieder freige-
  547. ; geben sowie die gesetzten Bookmarks gelöscht. Der Puffer ist nach dieser
  548. ; Funktion also in dem Zustand, als wenn er gerade geöffnet worden wäre.
  549. ;----------------------------------------------------------------------------
  550. ; Synopsis:    success = ClearBuf (BufHandle)
  551. ;                D0*                  A0
  552. ;
  553. ; Eingaben:    A0 --> APTR auf den BufHandle des zu löschenden Puffers
  554. ;
  555. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  556. ;                          - FALSE, wenn Fehler (Info mit »LastError()«)
  557. ;
  558. ; Bemerkung:   Diese Funktion löscht automatisch die Prozessor-Caches.
  559. ;
  560. ; Siehe auch:  »OpenBuf()«, »CloseBuf()«, »FileToBuf()«, »BufToFile()«,
  561. ;              »DuplicateBuf()«, »BufInfo()«
  562. ;============================================================================
  563.  
  564. ;*** extra.library / DuplicateBuf()          (OFFSET -90) V1.323 ***
  565. ;============================================================================
  566. ; Diese Funktion erstellt einen neuen dynamischen Puffer, dessen Daten eine
  567. ; genaue Kopie des angegebenen Quell-Puffers darstellen. Das heißt, es wer-
  568. ; den nicht nur die regulären Daten kopiert, sondern auch die Such-Daten so-
  569. ; wie die Bookmarks. Außerdem wird auch die aktuelle Cursorposition von dem
  570. ; Quell-Puffer übernommen. Sie erhalten als Ergebnis einen Zeiger auf den
  571. ; neu initialisierten BufHandle.
  572. ;----------------------------------------------------------------------------
  573. ; Synopsis:    bufHandle = DuplicateBuf (BufHandle)
  574. ;                 D0*                        A0
  575. ;
  576. ; Eingaben:    A0 --> APTR BufHandle des zu duplizierenden Puffers
  577. ;
  578. ; Ergebnis:    D0 --> APTR - Zeiger auf den neu initialisierten BufHandle
  579. ;                          - 0-PTR, wenn Fehler (Info mit »LastError()«)
  580. ;
  581. ; Bemerkung:   Auch ein mittels dieser Funktion geöffneter Puffer wird mit
  582. ;              der Funktion »CloseBuf()« wieder geschlossen.
  583. ;              Diese Funktion löscht automatisch die Prozessor-Caches.
  584. ;
  585. ; Siehe auch:  »OpenBuf()«, »CloseBuf()«, »FileToBuf()«, »BufToFile()«,
  586. ;              »ClearBuf()«, »BufInfo()«
  587. ;
  588. ;----------------------------------------------------------------------------
  589. ;--- Veränderungen seit v2.062 ----------------------------------------------
  590. ;----------------------------------------------------------------------------
  591. ;
  592. ; Bemerkung:   Diese Funktion ist veraltet, bitte benutzen Sie stattdessen
  593. ;              die Funktion »v2_DuplicateBuf()«, welche zusätzlich die Angabe
  594. ;              von Speicher-Flags ermöglicht, um z.B. Audio- oder Grafik-Daten
  595. ;              gezielt ins CHIP-Ram zu duplizieren.
  596. ;
  597. ;   ACHTUNG:   Diese Funktion hat und wird immer DEN GLEICHEN Speichertyp für
  598. ;   ¯¯¯¯¯¯¯¯   den Datenbereich des neuen Puffers verwenden wie der originale
  599. ;              Puffer auch verwendet.
  600. ;
  601. ; Siehe auch:  »v2_OpenBuf()«, »v2_FileToBuf()«
  602. ;============================================================================
  603.  
  604. ;*** extra.library / v2_DuplicateBuf()       (OFFSET -312) V2.062 ***
  605. ;============================================================================
  606. ; Diese Funktion erstellt einen neuen dynamischen Puffer, dessen Daten eine
  607. ; genaue Kopie des angegebenen Quell-Puffers darstellen. Das heißt, es wer-
  608. ; den nicht nur die regulären Daten kopiert, sondern auch die Such-Daten so-
  609. ; wie die Bookmarks. Außerdem wird auch die aktuelle Cursorposition von dem
  610. ; Quell-Puffer übernommen. Dabei kann noch angegeben werden, welcher Speicher-
  611. ; typ für den Datenbereich verwendet werden soll. Sie erhalten als Ergebnis
  612. ; einen Zeiger auf den neu initialisierten BufHandle.
  613. ;----------------------------------------------------------------------------
  614. ; Synopsis:    bufHandle = v2_DuplicateBuf (BufHandle, MemType)
  615. ;                 D0*                          A0        D0!
  616. ;
  617. ; Eingaben:    A0 --> APTR  BufHandle des zu duplizierenden Puffers
  618. ;              D0 --> ULONG eine Kombination von Speicher-Flags wie sie in
  619. ;                           der Include-Datei »exec/memory.i« definiert sind.
  620. ;
  621. ; Ergebnis:    D0 --> APTR - Zeiger auf den neu initialisierten BufHandle
  622. ;                          - 0-PTR, wenn Fehler (Info mit »LastError()«)
  623. ;
  624. ; Bemerkung:   Es gelten die gleichen Konditionen wie bei »DuplicateBuf()«
  625. ;
  626. ; Siehe auch:  »v2_OpenBuf()«, »v2_FileToBuf()«
  627. ;============================================================================
  628.  
  629. ;*** extra.library / BufInfo()               (OFFSET -96) V1.323 ***
  630. ;============================================================================
  631. ; Mit dieser Funktion können Sie sich spezifische Daten über den momentanen
  632. ; Zustand eines Puffers holen. Als Ergebnis erhalten Sie einen Adress-Zeiger
  633. ; auf eine entsprechend ausgefüllte »BufInfoBlock«-Struktur (s. extradefs.i).
  634. ;----------------------------------------------------------------------------
  635. ; Synopsis:    BIBStruct = BufInfo (BufHandle)
  636. ;                 D0*                  A0
  637. ;
  638. ; Eingaben:    A0 --> APTR auf den gewünschten BufHandle
  639. ;
  640. ; Ergebnis:    D0 --> APTR - auf ausgefüllte »BIBStruct« (s. extradefs.i)
  641. ;                          - 0-PTR, wenn Fehler (Info mit »LastError()«)
  642. ;
  643. ; Bemerkung:   Sie brauchen sich nicht um die Beschaffung bzw. Freigabe des
  644. ;              »BufInfoBlocks« zu kümmern, da der benötigte Speicherplatz
  645. ;              Ihrem Task beim Öffnen der »extra.library« zur Verfügung ge-
  646. ;              stellt wird, und dann beim Schließen der Library auch automa-
  647. ;              tisch wieder freigegeben wird. Beachten Sie jedoch, daß die
  648. ;              Struktur aufgrund dieser Verwaltungsmethode beim jeweils
  649. ;              nächsten Aufruf dieser Funktion wieder überschrieben wird.
  650. ;
  651. ;   ACHTUNG:   In C und C++ ist das APTR-Ergebnis als Typ STRUCT BIBStruct*
  652. ;   ¯¯¯¯¯¯¯¯   zu behandeln.
  653. ;
  654. ; Siehe auch:  »OpenBuf()«, »CloseBuf()«, »FileToBuf()«, »BufToFile()«,
  655. ;              »ClearBuf()«, »DuplicateBuf()«
  656. ;============================================================================
  657.  
  658. ;*** extra.library / SeekBuf()               (OFFSET -102) V1.323 ***
  659. ;============================================================================
  660. ; Mit dieser Funktion können Sie die aktuelle Cursorposition innerhalb des
  661. ; angegebenen Puffers an jede beliebige Stelle setzten, und damit bestimmen,
  662. ; wo im Puffer die folgende(n) Pufferoperation(en) wirken soll(en). Es wird
  663. ; zuerst die durch den »Mode« angegebene Positionierung durchgeführt, und
  664. ; dann der Offsetwert »Position«, welcher sowohl positiv, als auch negativ
  665. ; sein darf, zu dieser Position hinzuaddiert.
  666. ;----------------------------------------------------------------------------
  667. ; Synopsis:    oldPos = SeekBuf (BufHandle, Position, Mode)
  668. ;                D0*                A0         D0      D1
  669. ;
  670. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  671. ;              D0 --> LONG  Offset, der zu der durch den »Mode« spezifizier-
  672. ;                           ten Position addiert wird (positiv od. negativ)
  673. ;              D1 --> ULONG der zu verwendende »Mode« (s. extradefs.i)
  674. ;
  675. ; Ergebnis:    D0 --> LONG - alte Position, wenn alles in Ordnung
  676. ;                             (ACHTUNG: Zählbeginn = 0 !!)
  677. ;                          - negativ, wenn Fehler (Info mit »LastError()«)
  678. ;
  679. ; Bemerkung:   Mit dieser Funktion können Sie außerdem schnell die aktuelle
  680. ;              Cursorposition ermitteln, wenn Ihnen der Weg über »BufInfo()«
  681. ;              zu aufwendig ist. Setzen Sie zu diesem Zweck den Parameter
  682. ;              »Mode« auf »SKM_Current«, und den Parameter »Position« auf
  683. ;              NULL. Mit diesem Aufruf bleibt die aktuelle Cursorposition
  684. ;              tatsächlich zwar unverändert, Sie bekommen sie aber auch als
  685. ;              angeblich alte Position zurückgeliefert.
  686. ;
  687. ;   ACHTUNG:   Wenn ein Fehler auftritt, dann bleibt die alte Cursor-
  688. ;   ¯¯¯¯¯¯¯¯   position erhalten !!
  689. ;
  690. ; Siehe auch:  »Store()«, »InsertBuf()«, »InsertFile()«, »Replace()«,
  691. ;              »Get()«, »Clear()«
  692. ;============================================================================
  693.  
  694. ;*** extra.library / Store()                 (OFFSET -108) V1.323 ***
  695. ;============================================================================
  696. ; Diese Funktion schreibt die angegebenen Daten in den durch den BufHandle
  697. ; spezifizierten Puffer. Die Daten werden an der aktuellen Cursorposition
  698. ; eingefügt. Eventuell schon vorhandene Daten an dieser Stelle werden ent-
  699. ; sprechend nach hinten verschoben. Die aktuelle Cursorposition wird auto-
  700. ; matisch nachgeführt, und steht nach dem Aufruf dementsprechend auf dem er-
  701. ; sten Byte nach den eingefügten Daten.
  702. ;----------------------------------------------------------------------------
  703. ; Synopsis:    newPos = Store (BufHandle, Data, Size)
  704. ;               D0*               A0      A1!    D0
  705. ;
  706. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  707. ;              A1 --> APTR  auf die einzufügenden Daten
  708. ;              D0 --> ULONG Menge der Daten in Bytes
  709. ;
  710. ; Ergebnis:    D0 --> LONG - die neue Cursorposition, wenn alles in Ordnung
  711. ;                             (ACHTUNG: Zählbeginn = 0 !!)
  712. ;                          - negativ, wenn Fehler (Info mit »LastError()«)
  713. ;
  714. ; Bemerkung:   Diese Funktion löscht automatisch die Prozessor-Caches.
  715. ;
  716. ; Siehe auch:  »SeekBuf()«, »InsertBuf()«, »InsertFile()«, »Replace()«,
  717. ;              »Get()«, »Clear()«
  718. ;============================================================================
  719.  
  720. ;*** extra.library / InsertBuf()             (OFFSET -114) V1.323 ***
  721. ;============================================================================
  722. ; Diese Funktion fügt die Daten eines anderen, bereits bestehenden Puffers,
  723. ; an der aktuellen Cursorposition des gewünschten Puffers ein. Dies ist von
  724. ; Nutzen, wenn viele Einzeldaten am Anfang eines Puffers eingefügt werden
  725. ; sollen, was nämlich je nach Menge der nach hinten zu schiebenden Daten eine
  726. ; sehr zeitraubende Angelegenheit werden kann. In solchen Fällen öffnen Sie
  727. ; einfach einen neuen Puffer, wo Sie die Daten dann fortlaufend (also immer
  728. ; ans Pufferende anfügend) speichern können, wobei nichts nach hinten gescho-
  729. ; ben werden muß. Ist das getan, dann verwenden Sie diese Funktion, um die
  730. ; Daten nun in Ihren eigentlichen Arbeitspuffer einzufügen, womit jetzt nur
  731. ; einmal die ganzen Restdaten verschoben werden müssen. Die Cursorposition
  732. ; wird automatisch nachgeführt, und steht nach dem Aufruf dementsprechend auf
  733. ; dem ersten Byte nach den eingefügten Daten.
  734. ;----------------------------------------------------------------------------
  735. ; Synopsis:    inserted = InsertBuf (BufHandle1, BufHandle2)
  736. ;                D0*                     A0          A1
  737. ;
  738. ; Eingaben:    A0 --> APTR auf den gewünschten Ziel-BufHandle
  739. ;              A1 --> APTR auf den zu verwendenden Quell-BufHandle
  740. ;
  741. ; Ergebnis:    D0 --> LONG - Anzahl der eingefügten Bytes
  742. ;                          - negativ, wenn Fehler (Info mit »LastError()«)
  743. ;
  744. ; Bemerkung:   Diese Funktion löscht automatisch die Prozessor-Caches.
  745. ;
  746. ; Siehe auch:  »SeekBuf()«, »Store()«, »InsertFile()«, »Replace()«, »Get()«,
  747. ;              »Clear()«
  748. ;============================================================================
  749.  
  750. ;*** extra.library / InsertFile()            (OFFSET -120) V1.323 ***
  751. ;============================================================================
  752. ; Diese Funktion fügt die Daten der angegebenen Datei in den gewünschten
  753. ; Puffer an der aktuellen Cursorposition ein. Die Cursorposition wird auto-
  754. ; matisch nachgeführt, und steht nach dem Aufruf dementsprechend auf dem er-
  755. ; sten Byte nach den eingefügten Daten.
  756. ;----------------------------------------------------------------------------
  757. ; Synopsis:    inserted = InsertFile (BufHandle, FileName)
  758. ;                D0*                     A0        A1!
  759. ;
  760. ; Eingaben:    A0 --> APTR   auf den gewünschten BufHandle
  761. ;              A1 --> STRPTR auf einen AmigaDOS-Dateinamen(+0)
  762. ;
  763. ; Ergebnis:    D0 --> LONG - Anzahl der eingefügten Bytes
  764. ;                          - negativ, wenn Fehler (Info mit »LastError()«)
  765. ;
  766. ; Bemerkung:   Diese Funktion löscht automatisch die Prozessor-Caches.
  767. ;
  768. ;   ACHTUNG:   Diese Funktion darf NUR von vollwertigen DOS-Prozessen auf-
  769. ;   ¯¯¯¯¯¯¯¯   gerufen werden. Ein normaler EXEC-Task ist nicht ausreichend.
  770. ;
  771. ; Siehe auch:  »SeekBuf()«, »Store()«, »InsertBuf()«, »Replace()«, »Get()«,
  772. ;              »Clear()«
  773. ;============================================================================
  774.  
  775. ;*** extra.library / Replace()               (OFFSET -126) V1.323 ***
  776. ;============================================================================
  777. ; Mit dieser Funktion können Sie die Daten an der aktuellen Cursorposition
  778. ; durch andere Daten ersetzen. Sollte die Länge der neuen Daten von der
  779. ; Länge der alten Daten abweichen, dann werden die nachfolgenden Daten im
  780. ; Puffer automatisch dementsprechend nach vorne oder hinten verschoben. Die
  781. ; aktuelle Cursorposition wird automatisch nachgeführt, und steht nach dem
  782. ; Aufruf dementsprechend auf dem ersten Byte hinter den neuen Daten.
  783. ;----------------------------------------------------------------------------
  784. ; Synopsis:    newPos = Replace (BufHandle, Data, Size, OldSize)
  785. ;               D0*                 A0       A1!   D0     D1
  786. ;
  787. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  788. ;              A1 --> APTR  auf die neuen Daten
  789. ;              D0 --> ULONG Menge der neuen Daten in Bytes
  790. ;              D1 --> ULONG Menge der alten Daten in Bytes
  791. ;
  792. ; Ergebnis:    D0 --> LONG - die neue Cursorposition, wenn alles in Ordnung
  793. ;                             (ACHTUNG: Zählbeginn = 0 !!)
  794. ;                          - negativ, wenn Fehler (Info mit »LastError()«)
  795. ;
  796. ; Bemerkung:   Diese Funktion löscht automatisch die Prozessor-Caches.
  797. ;
  798. ; Siehe auch:  »SeekBuf()«, »Store()«, »InsertBuf()«, »InsertFile()«,
  799. ;              »Get()«, »Clear()«
  800. ;============================================================================
  801.  
  802. ;*** extra.library / Get()                   (OFFSET -132) V1.323 ***
  803. ;============================================================================
  804. ; Mit dieser Funktion können Sie sich die physische Adresse der aktuellen
  805. ; Cursorposition besorgen. Diese Adresse können Sie dann für andere Funk-
  806. ; tionen verwenden (z.B. »Text()« der graphics.library, um die Daten auszu-
  807. ; geben). Die Daten brauchen also für solche Anwendungen nicht extra noch
  808. ; einmal ausgelesen werden (wär' ja auch unsinnig).
  809. ;----------------------------------------------------------------------------
  810. ; Synopsis:    address = Get (BufHandle)
  811. ;                D0*             A0
  812. ;
  813. ; Eingaben:    A0 --> APTR auf den gewünschten BufHandle
  814. ;
  815. ; Ergebnis:    D0 --> APTR - auf die Daten an der aktuellen Cursorposition
  816. ;                          - 0-PTR, wenn akt. Cursorposition = Pufferende
  817. ;                          - negativ, wenn Fehler (Info mit »LastError()«)
  818. ;
  819. ; Bemerkung:   Die gelieferte Adresse sollte NUR für lesende Zugriffe ver-
  820. ;              wendet werden, da alles was man »per Hand« an dieser Stelle
  821. ;              verändert nicht vom Puffersystem registriert wird.
  822. ;
  823. ;   ACHTUNG:   Die ermittelte Adresse wird mit Aufruf der nächsten Puffer-
  824. ;   ¯¯¯¯¯¯¯¯   funktion, welche Daten speichert od. löscht, wieder ungültig.
  825. ;              Eventuell worden die Daten dann nämlich verlagert.
  826. ;
  827. ; Siehe auch:  »SeekBuf()«, »Store()«, »InsertBuf()«, »InsertFile()«,
  828. ;              »Replace()«, »Clear()«
  829. ;============================================================================
  830.  
  831. ;*** extra.library / Clear()                 (OFFSET -138) V1.323 ***
  832. ;============================================================================
  833. ; Diese Funktion löscht die angegebene Anzahl Datenbytes ab der aktuellen
  834. ; Cursorposition in dem durch den BufHandle spezifizierten Puffer. Eventuell
  835. ; noch dahinter stehende Daten werden wieder nach vorne aufgerückt. Die ak-
  836. ; tuelle Cursorposition bleibt unverändert, da die nachfolgenden Daten, auf
  837. ; denen die aktuelle Position nach der Operation ja steht, wieder nach vorne
  838. ; auf die Position der ehemaligen Daten aufrücken.
  839. ;----------------------------------------------------------------------------
  840. ; Synopsis:    end = Clear (BufHandle, Size)
  841. ;              D0*             A0       D0
  842. ;
  843. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  844. ;              D0 --> ULONG Anzahl der zu löschenden Datenbytes
  845. ;
  846. ; Ergebnis:    D0 --> BOOL - UPPER, wenn noch Daten aufgerückt sind
  847. ;                          - EQUAL, wenn Löschaktion Pufferende erreicht hat
  848. ;                          - LOWER, wenn Fehler (Info mit »LastError()«)
  849. ;
  850. ; Bemerkung:   Diese Funktion löscht automatisch die Prozessor-Caches.
  851. ;
  852. ; Siehe auch:  »SeekBuf()«, »Store()«, »InsertBuf()«, »InsertFile()«,
  853. ;              »Replace()«, »Get()«
  854. ;============================================================================
  855.  
  856. ;*** extra.library / FindData()              (OFFSET -144) V1.323 ***
  857. ;============================================================================
  858. ; Mit dieser Funktion können Sie bestimmte Datenabschnitte innerhalb eines
  859. ; Puffers suchen. Die Suche beginnt dabei an der aktuellen Cursorposition.
  860. ; Werden die Daten gefunden, dann wird die gefundene Position automatisch
  861. ; zur aktuellen Cursorposition, im anderen Falle bleibt die alte Cursorposi-
  862. ; tion erhalten. Im Zusammenspiel mit den anderen Find-Funktionen und der
  863. ; Funktion »Replace()« kann man so z.B. einfach eine Search/Replace-Schleife
  864. ; realisieren. Der anzugebende Schlüsselwert dient bei späteren Aufrufen von
  865. ; »FindNext()/FindPrev()« als Identifikation der gewünschten Daten, welche
  866. ; vorher mit dieser Funktion initialisiert wurden. Es sind max. 8 Schlüssel-
  867. ; werte pro Puffer möglich. Sie könnten die ersten 4 Schlüssel z.B. verwen-
  868. ; den, um nach SPACES, TABS, LF's und FF's zu suchen, womit Sie auf einfache
  869. ; Art u. Weise eine Funktion hätten, mit der Sie den Cursor Wort-, Zeilen-
  870. ; oder auch Seitenweise weiter- bzw. zurückschalten könnten.
  871. ;----------------------------------------------------------------------------
  872. ; Synopsis:    success = FindData (BufHandle, Key, Data, Size)
  873. ;                D0*                  A0      D0   A1!    D1
  874. ;
  875. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  876. ;              D0 --> ULONG Kennungs-Schlüssel dieser Daten (0-7 !!)
  877. ;              A1 --> APTR  auf die zu suchenden Daten
  878. ;              D1 --> ULONG Länge der zu suchenden Daten in Byte
  879. ;
  880. ; Ergebnis:    D0 --> BOOL - UPPER, wenn die Daten gefunden wurden
  881. ;                          - EQUAL, wenn sie nicht gefunden wurden
  882. ;                          - LOWER, wenn Fehler (Info mit »LastError()«)
  883. ;
  884. ; Bemerkung:   Der Speicher Ihrer übergebenen Such-Daten kann nach Aufruf der
  885. ;              Funktion anderweitig weiterverwendet werden, da die Such-Daten
  886. ;              für die Verwendung mit den Funktionen »FindNext()/FindPrev()«
  887. ;              intern kopiert und zwischengespeichert werden. Wenn schon Daten
  888. ;              von einem früheren Aufruf dieser Funktion für den gleichen
  889. ;              Schlüssel vorhanden sind, dann werden diese freigegeben und die
  890. ;              jetzt angegebenen Daten an deren Stelle gespeichert.
  891. ;              Diese Funktion löscht automatisch die Prozessor-Caches.
  892. ;
  893. ; Siehe auch:  »FindNext()«, »FindPrev()«, »FreeFinds()«, »SetBookmark()«,
  894. ;              »GotoBookmark()«
  895. ;============================================================================
  896.  
  897. ;*** extra.library / FindNext()              (OFFSET -150) V1.323 ***
  898. ;============================================================================
  899. ; Diese Funktion sucht das nächste Auftreten der Daten eines vorangegangenen
  900. ; »FindData()«-Aufrufs. Die Suche beginnt wie bei o.g. Funktion wieder an der
  901. ; aktuellen Cursorposition. Mit dem Schlüssel geben Sie an, von welchen Daten
  902. ; das nächste Auftreten gesucht werden soll.
  903. ;----------------------------------------------------------------------------
  904. ; Synopsis:    success = FindNext (BufHandle, Key)
  905. ;                D0*                  A0      D0
  906. ;
  907. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  908. ;              D0 --> ULONG Schlüsselwert der zu suchenden Daten (0-7 !!)
  909. ;
  910. ; Ergebnis:    D0 --> BOOL - UPPER, wenn die Daten gefunden wurden
  911. ;                          - EQUAL, wenn sie nicht gefunden wurden
  912. ;                          - LOWER, wenn Fehler (Info mit »LastError()«)
  913. ;
  914. ; Siehe auch:  »FindData()«, »FindPrev()«, »FreeFinds()«, »SetBookmark()«,
  915. ;              »GotoBookmark()«
  916. ;============================================================================
  917.  
  918. ;*** extra.library / FindPrev()              (OFFSET -156) V1.323 ***
  919. ;============================================================================
  920. ; Diese Funktion sucht das vorige Auftreten der Daten eines vorangegangenen
  921. ; »FindData()«-Aufrufs. Die Suche beginnt wie bei o.g. Funktion wieder an der
  922. ; aktuellen Cursorposition. Mit dem Schlüssel geben Sie an, von welchen Daten
  923. ; das vorhergehende Auftreten gesucht werden soll.
  924. ;----------------------------------------------------------------------------
  925. ; Synopsis:    success = FindPrev (BufHandle, Key)
  926. ;                D0*                  A0      D0
  927. ;
  928. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  929. ;              D0 --> ULONG Schlüsselwert der zu suchenden Daten (0-7 !!)
  930. ;
  931. ; Ergebnis:    D0 --> BOOL - UPPER, wenn die Daten gefunden wurden
  932. ;                          - EQUAL, wenn sie nicht gefunden wurden
  933. ;                          - LOWER, wenn Fehler (Info mit »LastError()«)
  934. ;
  935. ; Siehe auch:  »FindData()«, »FindNext()«, »FreeFinds()«, »SetBookmark()«,
  936. ;              »GotoBookmark()«
  937. ;============================================================================
  938.  
  939. ;*** extra.library / FreeFinds()             (OFFSET -162) V1.323 ***
  940. ;============================================================================
  941. ; Diese Funktion gibt die internen Kopien aller Such-Daten (alle vorhandenen
  942. ; Schlüsselwerte) wieder frei. Dies kann manchmal sehr nützlich sein, wenn
  943. ; Speichermangel besteht, und die Daten ohnehin nicht mehr benötigt werden.
  944. ;----------------------------------------------------------------------------
  945. ; Synopsis:    success = FreeFinds (BufHandle)
  946. ;                D0*                   A0
  947. ;
  948. ; Eingaben:    A0 --> APTR auf den gewünschten BufHandle
  949. ;
  950. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  951. ;                          - FALSE, wenn Fehler (Info mit »LastError()«)
  952. ;
  953. ; Bemerkung:   Nach Aufruf dieser Funktion müssen Sie erst wieder neue Daten
  954. ;              via »FindData()« initialisieren, bevor Sie wieder die Funk-
  955. ;              tionen für fortlaufendes bzw. rückläufiges Suchen verwenden
  956. ;              können.
  957. ;              Diese Funktion löscht automatisch die Prozessor-Caches.
  958. ;
  959. ; Siehe auch:  »FindData()«, »FindNext()«, »FindPrev()«, »SetBookmark()«,
  960. ;              »GotoBookmark()«
  961. ;============================================================================
  962.  
  963. ;*** extra.library / SetBookmark()           (OFFSET -168) V1.323 ***
  964. ;============================================================================
  965. ; Mit dieser Funktion erklären Sie die aktuelle Cursorposition zu einer
  966. ; Bookmark. Diese Bookmarks (max. 16 pro Puffer) werden bei Speicher- oder
  967. ; Löschoperationen im Puffer automatisch neuberechnet, und halten somit
  968. ; immer die markierte Stelle im »Gedächtnis«.
  969. ;----------------------------------------------------------------------------
  970. ; Synopsis:    success = SetBookmark (BufHandle, Key)
  971. ;                D0*                     A0      D0
  972. ;
  973. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  974. ;              D0 --> ULONG Nummer der zu setzenden Bookmark (0..15 !!)
  975. ;
  976. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  977. ;                          - FALSE, wenn Fehler (Info mit »LastError()«)
  978. ;
  979. ; Bemerkung:   Beachten Sie, daß jede Bookmark nur einmal vergeben werden
  980. ;              kann. Das heißt, wenn Sie eine Bookmark verwenden, die Sie
  981. ;              schon früher gesetzt haben, dann wird diese jetzt mit der
  982. ;              neuen Position überschrieben.
  983. ;
  984. ; Siehe auch:  »FindData()«, »FindNext()«, »FindPrev()«, »FreeFinds()«,
  985. ;              »GotoBookmark()«
  986. ;============================================================================
  987.  
  988. ;*** extra.library / GotoBookmark()          (OFFSET -174) V1.323 ***
  989. ;============================================================================
  990. ; Mit dieser Funktion rufen Sie eine vorher gesetzte Bookmark ab. Das heißt,
  991. ; daß die aktuelle Cursorposition auf die in der Bookmark gespeicherten Po-
  992. ; sition gesetzt wird. Dies funktioniert natürlich nur, wenn die Daten an be-
  993. ; sagter Stelle noch existieren, d.h. sie noch nicht gelöscht wurden. Alter-
  994. ; nativ zu dieser Funktion können Sie auch »SeekBuf()« verwenden.
  995. ;----------------------------------------------------------------------------
  996. ; Synopsis:    success = GotoBookmark (BufHandle, Key)
  997. ;                D0*                      A0      D0
  998. ;
  999. ; Eingaben:    A0 --> APTR  auf den gewünschten BufHandle
  1000. ;              D0 --> ULONG Nummer der gewünschten Bookmark (0..15 !!)
  1001. ;
  1002. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  1003. ;                          - FALSE, wenn Fehler (Info mit »LastError()«)
  1004. ;
  1005. ; Bemerkung:   Sollte diese Funktion fehlschlagen, dann bleibt die alte
  1006. ;              Cursorposition erhalten.
  1007. ;
  1008. ; Siehe auch:  »SeekBuf()«, »FindData()«, »FindNext()«, »FindPrev()«,
  1009. ;              »FreeFinds()«, »SetBookmark()«
  1010. ;============================================================================
  1011.  
  1012. ;*** extra.library / FindString()            (OFFSET -180) V1.323 ***
  1013. ;============================================================================
  1014. ; Diese Funktion sucht eine Bytefolge innerhalb einer anderen Bytefolge. Die
  1015. ; Suche findet dabei »Case-Sensitiv« statt, das heißt, »A« ist ungleich »a«.
  1016. ; Der verwendete Suchalgorithmus arbeitet mit »3-Phase-PreCheck«, womit so-
  1017. ; gar auf alten 68000er-Amigas noch ein Datendurchsatz von ca. 130 KByte/Sec
  1018. ; erreicht werden kann (je nach Auslastung des Multitaskings).
  1019. ;----------------------------------------------------------------------------
  1020. ; Synopsis:    position = FindString (Source, SourceLen, Find, FindLen)
  1021. ;                 D0*                   A0!      D0      A1!     D1
  1022. ;
  1023. ; Eingaben:    A0 --> STRPTR auf Adresse der zu durchsuchenden Bytefolge
  1024. ;              D0 --> ULONG  Länge der zu durchsuchenden Folge in Byte
  1025. ;              A1 --> STRPTR auf Adresse der zu suchenden Bytefolge
  1026. ;              D1 --> ULONG  Länge der zu suchenden Folge in Byte
  1027. ;
  1028. ; Ergebnis:    D0 --> LONG - die Position, ab welchem Byte der durchsuchten
  1029. ;                            Bytefolge die Gesuchte in ihr enthalten ist
  1030. ;                             (ACHTUNG: Zählbeginn = 1 !!)
  1031. ;                          - ist NULL, wenn die gesuchte Bytefolge nicht in
  1032. ;                            der Durchsuchten enthalten ist
  1033. ;                          - ist negativ, wenn ein Fehler aufgetreten ist
  1034. ;                            (Find-String länger als Source-String)
  1035. ;
  1036. ; Bemerkung:   Ich habe die Zeiger auf die Bytefolgen als STRPTR deklariert,
  1037. ;              da man diese Funktion wohl meistens für die Suche innerhalb
  1038. ;              von alphanumerischen Zeichenketten benutzen wird. Die Funktion
  1039. ;              kann aber genausogut zum Suchen von nicht druckbaren Zeichen
  1040. ;              benutzt werden, d.h. sie bricht ihre Arbeit nicht etwa beim
  1041. ;              Auftauchen eines 0-Bytes o.ä. ab. Um dies deutlich zu machen,
  1042. ;              rede ich hier auch absichtlich immerzu nur von »Bytefolgen«,
  1043. ;              und nicht etwa von »Strings« oder »Zeichenketten«.
  1044. ;
  1045. ; Siehe auch:  »GetLength()«
  1046. ;============================================================================
  1047.  
  1048. ;*** extra.library / GetLength()             (OFFSET -186) V1.323 ***
  1049. ;============================================================================
  1050. ; Diese Funktion ermittelt die Länge einer Bytefolge, welche mit dem spezi-
  1051. ; fizierten Byte abgeschlossen ist. Man kann so z.B. die Länge eines 0-ter-
  1052. ; minierten Strings ermitteln oder in Textpuffern die Linefeeds suchen und
  1053. ; somit die Länge einer Zeile ermitteln etc..
  1054. ;----------------------------------------------------------------------------
  1055. ; Synopsis:    length = GetLength (Start, EndByte, MaxBytes)
  1056. ;                D0*                A0!      D0       D1
  1057. ;
  1058. ; Eingaben:    A0 --> STRPTR auf die Startadresse der Bytefolge
  1059. ;              D0 --> UBYTE  zu suchendes EndByte (0-255)
  1060. ;              D1 --> ULONG  max. zu prüfende Byteanzahl (s. Bemerkung)
  1061. ;
  1062. ; Ergebnis:    D0 --> LONG - Länge der Bytefolge (ohne EndByte)
  1063. ;                          - negativ, wenn innerhalb eines angegebenen Be-
  1064. ;                            reichs kein EndByte gefunden wurde
  1065. ;
  1066. ; Bemerkung:   Der Parameter »MaxBytes« ist ein Grenzwert. Wird er erreicht,
  1067. ;              dann wird die Prüfung der Bytefolge abgebrochen. Dies erweist
  1068. ;              sich als nützlich, wenn innerhalb eines Puffers gesucht wird,
  1069. ;              dieser jedoch nicht überschritten werden soll, wenn bis zu
  1070. ;              dessen Ende kein EndByte gefunden wurde. Soll jedoch wirklich
  1071. ;              bis zum Auftauchen des Endwertes gesucht werden, dann geben
  1072. ;              Sie für diesen Parameter einfach -1 an.
  1073. ;               Ich habe den Zeiger auf die Bytefolge als STRPTR deklariert,
  1074. ;              da man diese Funktion wohl meistens für die Längenbestimmung
  1075. ;              von alphanumerischen Zeichenketten benutzen wird. Die Funktion
  1076. ;              kann aber genausogut zur Längenbestimmung eines Datenpuffers
  1077. ;              benutzt werden, d.h. sie bricht ihre Arbeit nicht etwa beim
  1078. ;              Auftauchen eines 0-Bytes o.ä. ab (es sei denn, dieses Byte ist
  1079. ;              als »EndByte« spezifiziert). Um dies deutlich zu machen, rede
  1080. ;              ich hier auch absichtlich immerzu nur von einer »Bytefolge«,
  1081. ;              und nicht etwa von einem »String« oder einer »Zeichenkette«.
  1082. ;
  1083. ; Siehe auch:  »FindString()«
  1084. ;============================================================================
  1085.  
  1086. ;*** extra.library / LastError()             (OFFSET -192) V1.323 ***
  1087. ;============================================================================
  1088. ; Ähnlich der Funktion »IoErr()« der dos.library ermittelt diese Funktion
  1089. ; die Nummer des zuletzt aufgetretenen »extra.library«-Fehlers innerhalb des
  1090. ; jeweiligen Tasks, der diese Funktion aufruft.
  1091. ;----------------------------------------------------------------------------
  1092. ; Synopsis:    error = LastError (VOID)
  1093. ;               D0
  1094. ;
  1095. ; Ergebnis:    D0 --> ULONG Fehlernummer (s. extradefs.i)
  1096. ;============================================================================
  1097.  
  1098. ;*** extra.library / LongToString()          (OFFSET -198) V1.323 ***
  1099. ;============================================================================
  1100. ; Mit dieser Funktion können Sie eine 32-Bit-Binärzahl (LONG) in einen druck-
  1101. ; baren Dezimalstring umwandeln. Die Zahl wird dabei entweder als vorzeichen-
  1102. ; los od. vorzeichenbehaftet interpretiert. Der String wird mit einem 0-Byte
  1103. ; abgeschlossen. Als Ergebnis erhalten Sie den Adress-Zeiger auf den String.
  1104. ;----------------------------------------------------------------------------
  1105. ; Synopsis:    string = LongToString (Value, Flag)
  1106. ;                D0                    D0     D1
  1107. ;
  1108. ; Eingaben:    D0 --> LONG die umzuwandelnde Zahl
  1109. ;              D1 --> BOOL - TRUE  -> vorzeichenbehaftet
  1110. ;                          - FALSE -> vorzeichenlos
  1111. ;
  1112. ; Ergebnis:    D0 --> STRPTR auf den generierten Dezimalstring(+0)
  1113. ;
  1114. ; Bemerkung:   Sie brauchen sich nicht um die Beschaffung bzw. Freigabe des
  1115. ;              Stringpuffers zu kümmern, da der benötigte Speicherplatz Ihrem
  1116. ;              Task beim Öffnen der »extra.library« zur Verfügung gestellt
  1117. ;              wird, und dann beim Schließen der Library auch automatisch
  1118. ;              wieder freigegeben wird. Beachten Sie jedoch, daß der Puffer
  1119. ;              aufgrund dieser Verwaltungsmethode beim jeweils nächsten Auf-
  1120. ;              ruf dieser Funktion wieder überschrieben wird.
  1121. ;
  1122. ;   ACHTUNG:   Benutzen Sie IMMER den Rückgelieferten Wert als Startadresse
  1123. ;   ¯¯¯¯¯¯¯¯   zum Auslesen des Strings. Der Puffer hat zwar seine feste Po-
  1124. ;              sition, aber da der String rechtsbündig in diesem liegt, und
  1125. ;              der String selbst ja bei jedem Aufruf eine andere Länge haben
  1126. ;              kann, ändert sich damit natürlich auch die logischer Weise
  1127. ;              links liegende Startadresse.
  1128. ;
  1129. ; Siehe auch:  »StringToLong()«
  1130. ;===========================================================================
  1131.  
  1132. ;*** extra.library / StringToLong()          (OFFSET -204) V1.323 ***
  1133. ;============================================================================
  1134. ; Diese Funktion wandelt einen Dezimalstring, soweit möglich, in eine 32-Bit-
  1135. ; Binärzahl (LONG) um. Der Dezimalstring darf außer den Ziffern 0-9 an füh-
  1136. ; render Stelle auch ein Minuszeichen sowie an beliebiger Stelle einen Dezi-
  1137. ; malpunkt enthalten. Die Umwandlung erfolgt immer Vorzeichenbehaftet.
  1138. ;----------------------------------------------------------------------------
  1139. ; Synopsis:    value = StringToLong (DezString, Len)
  1140. ;               D0                      A0      D0
  1141. ;
  1142. ; Eingaben:    A0 --> STRPTR auf den umzuwandelnden Dezimalstring
  1143. ;                             (-2147483648 bis 2147483647)
  1144. ;              D0 --> ULONG  die Länge des Dezimalstrings
  1145. ;
  1146. ; Ergebnis:    D0 --> LONG die durch den String repräsentierte 32-Bit-Zahl
  1147. ;
  1148. ; Bemerkung:   Wenn Sie einen Dezimalpunkt im String angeben, dann wird nur
  1149. ;              der Vorkommawert (INTEGER) umgewandelt.
  1150. ;
  1151. ;   ACHTUNG:   Da das Ergebnis ja stets jeden beliebigen Wert annehmen kann,
  1152. ;   ¯¯¯¯¯¯¯¯   ist es nicht möglich, eine generelle Fehlermeldung Über das
  1153. ;              Rückgabe-Register auszugeben. Wenn Sie also nicht garantieren
  1154. ;              können, daß es sich um einen auswertbaren Dezimalstring
  1155. ;              handelte, dann sollten Sie im Anschluß an diese Funktion immer
  1156. ;              »LastError()« aufrufen, um festzustellen, ob das Ergebnis
  1157. ;              gültig ist, oder ob ein Fehler auftrat. (s.a. extradefs.i)
  1158. ;
  1159. ; Siehe auch:  »LongToString()«
  1160. ;============================================================================
  1161.  
  1162. ;*** extra.library / PackByteRun1()          (OFFSET -210) V1.323 ***
  1163. ;============================================================================
  1164. ; Diese Funktion führt an dem übergebenen Datenbereich eine cmpByteRun1-
  1165. ; Kompression durch. Dies ist die Standardmethode, mit der IFF-ILBM-Grafiken
  1166. ; komprimiert werden. Für andere Daten als Grafiken ist diese Methode auch
  1167. ; wenig geeignet, und wird bei solchen daher auch kaum Ersparnis bringen.
  1168. ;----------------------------------------------------------------------------
  1169. ; Synopsis:    outLen = PackByteRun1 (InBuf, InLen, OutBuf, OutLen)
  1170. ;               D0*                    A0!     D0    A1!     D1!
  1171. ;
  1172. ; Eingaben:    A0 --> APTR  auf die Quelldaten (zu komprimierende Daten)
  1173. ;              D0 --> ULONG Anzahl zu verarbeitender Bytes der Quelldaten
  1174. ;              A1 --> APTR  auf den Ausgabepuffer für die komprimierten Daten
  1175. ;              D1 --> ULONG Größe des Ausgabepuffers in Byte
  1176. ;
  1177. ; Ergebnis:    D0 --> LONG - Anzahl der geschriebenen Bytes im Ausgabepuffer
  1178. ;                          - negativ, wenn Ausgabepuffer zu klein
  1179. ;
  1180. ; Siehe auch:  »UnpackByteRun1()«
  1181. ;============================================================================
  1182.  
  1183. ;*** extra.library / UnpackByteRun1()        (OFFSET -216) V1.323 ***
  1184. ;============================================================================
  1185. ; Diese Funktion ist das Gegenstück zu »PackByteRun1()«. Sie entpackt die
  1186. ; von o.g. Funktion komprimierten Daten wieder zurück ins Originalformat.
  1187. ;----------------------------------------------------------------------------
  1188. ; Synopsis:    count = UnpackByteRun1 (InParam, OutBuf, OutLen)
  1189. ;               D0                      A0!      A1!      D0
  1190. ;
  1191. ; Eingaben:    A0 --> APTR  auf eine UnpackParam-Struktur (s. extradefs.i)
  1192. ;              A1 --> APTR  auf den Ausgabepuffer für die entpackten Daten
  1193. ;              D0 --> ULONG Größe des Ausgabepuffers in Bytes (= Anzahl zu
  1194. ;                           entpackender Bytes)
  1195. ;
  1196. ; Ergebnis:    D0 --> ULONG Anzahl tatsächlich entpackter Bytes, ist dieser
  1197. ;                           Wert kleiner als die gewünschte Anzahl, dann sind
  1198. ;                           alle Daten entpackt.
  1199. ;
  1200. ; Bemerkung:   Die Parameter-Struktur muß jeweils beim ersten Aufruf für ei-
  1201. ;              nen gepackten Datenblock initialisiert werden, und dient dann
  1202. ;              bei weiteren Aufrufen als Kennung des jeweiligen Datenblocks.
  1203. ;              Auf diese Weise können Sie einen größeren Datenblock in mehre-
  1204. ;              ren kleinen Einheiten wieder entpacken. Sie brauchen dann nur
  1205. ;              immer den Ausgabepuffer und dessen Größe neu angeben und die-
  1206. ;              selbe Struktur verwenden, bis alle Daten entpackt sind.
  1207. ;              Diese Funktion löscht automatisch die Prozessor-Caches.
  1208. ;
  1209. ;   ACHTUNG:   In C/C++ ist die A0-APTR-Eingabe als Typ STRUCT UnpackParam*
  1210. ;   ¯¯¯¯¯¯¯¯   zu behandeln.
  1211. ;
  1212. ; Siehe auch:  »PackByteRun1()«
  1213. ;============================================================================
  1214.  
  1215. ;*** extra.library / PrintIoError()          (OFFSET -222) V1.323 ***
  1216. ;============================================================================
  1217. ; Ist bei einer DOS-Operation ein Fehler aufgetreten, dann rufen Sie die
  1218. ; Funktion »IoErr()« der dos.library auf. Anschließend, wenn Sie eventuell
  1219. ; schon eine Fehlerbearbeitung vorgenommen haben, können Sie die Fehler-
  1220. ; nummer an diese Funktion weiterleiten. Es wird die verbale Fehlermeldung
  1221. ; zu dieser Nummer ermittelt, und dann die ganze Sache ordentlich mittels
  1222. ; »ShowMsg()« präsentiert. Sie brauchen dann nur noch darauf zu reagieren,
  1223. ; ob der Anwender einen nochmaligen Versuch wünscht oder nicht.
  1224. ;----------------------------------------------------------------------------
  1225. ; Synopsis:    button = PrintIoError (DOSErrNum)
  1226. ;                D0*                     D0
  1227. ;
  1228. ; Eingaben:    D0 --> ULONG ein beliebiger positiver Wert (meist ein DOS-Error)
  1229. ;
  1230. ; Ergebnis:    D0 --> BOOL - UPPER, wenn RETRY (linke Maustaste)
  1231. ;                          - EQUAL, wenn ABORT (rechte Maustaste)
  1232. ;                          - LOWER, wenn Fehler (Info mit »LastError()«)
  1233. ;
  1234. ; Bemerkung:   Wenn der angegebene Wert keine bekannte Fehlernummer ist, so
  1235. ;              wird die Meldung »UNKNOWN_ERROR_NUMBER« verwendet.
  1236. ;============================================================================
  1237.  
  1238. ;*** extra.library / FlipCase()              (OFFSET -228) V1.323 ***
  1239. ;============================================================================
  1240. ; Diese Funktion wandelt alle Kleinbuchstaben des angegebenen Strings in ihre
  1241. ; entsprechenden Großbuchstaben um, oder umgekehrt. Bei dieser Operation wer-
  1242. ; den auch Umlaute und internationale Sonderzeichen korrekt berücksichtigt,
  1243. ; sofern diese im normalen ASCII-Code, und nicht in Latin-Codesets o.ä. ver-
  1244. ; korksten Standards vorliegen.
  1245. ;----------------------------------------------------------------------------
  1246. ; Synopsis:    VOID FlipCase (String, Len, Flag)
  1247. ;                              A0!    D0    D1
  1248. ;
  1249. ; Eingaben:    A0 --> STRPTR auf den umzuwandelnden String
  1250. ;              D0 --> ULONG  die Länge des Strings
  1251. ;              D1 --> BOOL - TRUE  für klein -> groß
  1252. ;                          - FALSE für groß  -> klein
  1253. ;============================================================================
  1254.  
  1255. ;*** extra.library / CmpMem()                (OFFSET -234) V1.323 ***
  1256. ;============================================================================
  1257. ; Diese Funktion vergleicht zwei Speicherbereiche miteinander. Es wird auto-
  1258. ; matisch die schnellste Methode für den Vergleich gewählt.
  1259. ;----------------------------------------------------------------------------
  1260. ; Synopsis:    result = CmpMem (BlockA, BlockB, Size)
  1261. ;                D0*              A0      A1     D0
  1262. ;
  1263. ; Eingaben:    A0 --> APTR  auf die Startadresse von Bereich #1
  1264. ;              A1 --> APTR  auf die Startadresse von Bereich #2
  1265. ;              D0 --> ULONG Anzahl der zu prüfenden Bytes
  1266. ;
  1267. ; Ergebnis:    D0 --> ULONG - ist NULL, wenn die Bereiche identisch sind
  1268. ;                           - die Position der ersten Abweichung, wenn nicht
  1269. ;                             identisch (ACHTUNG: Zählbeginn = 1 !!)
  1270. ;============================================================================
  1271.  
  1272. ;*** extra.library / CopyMemI()              (OFFSET -240) V1.323 ***
  1273. ;============================================================================
  1274. ; Hierbei handelt es sich um eine intelligente Speicher-Kopierfunktion.
  1275. ; Intelligent in sofern, als daß sie automatisch erkennt, ob sich der Quell-
  1276. ; und der Zielbereich an irgendeiner Stelle überlappen. Ist dies der Fall,
  1277. ; wird ermittelt, ob mit aufwärts oder abwärts zählenden Adressen kopiert
  1278. ; werden muß, um ein überschreiben von noch nicht kopierten Quellabschnitten
  1279. ; zu vermeiden. Es wird der schnellste Weg für den Kopiervorgang gewählt.
  1280. ;----------------------------------------------------------------------------
  1281. ; Synopsis:    VOID CopyMemI (Source, Dest, Size)
  1282. ;                               A0    A1!    D0
  1283. ;
  1284. ; Eingaben:    A0 --> APTR  auf die Startadresse des Quell-Datenbereichs
  1285. ;              A1 --> APTR  auf die Startadresse des Ziel-Datenbereichs
  1286. ;              D0 --> ULONG Anzahl der zu kopierenden Bytes
  1287. ;
  1288. ; Bemerkung:   Diese Funktion löscht automatisch die Prozessor-Caches.
  1289. ;============================================================================
  1290.  
  1291. ;*** extra.library / FillMem()               (OFFSET -246) V1.323 ***
  1292. ;============================================================================
  1293. ; Diese Funktion füllt den angegebenen Speicherbereich mit dem spezifizierten
  1294. ; Wert. Anhand der Größe des Wertes wird ermittelt, ob eine Byte-, Wort- oder
  1295. ; Langwort-Füllung durchgeführt werden muß. Es wird der schnellste Weg für
  1296. ; die Füllung gewählt. Der Füllwert wird immer als Vorzeichenlos betrachtet.
  1297. ;----------------------------------------------------------------------------
  1298. ; Synopsis:    success = FillMem (Start, Size, Value)
  1299. ;                D0*               A0!    D0    D1
  1300. ;
  1301. ; Eingaben:    A0 --> APTR  auf den zu füllenden Bereich
  1302. ;                            (ACHTUNG: gerade Adresse bei WORD/LONG-Füllung)
  1303. ;              D0 --> ULONG Größe des Bereichs in Bytes !!
  1304. ;              D1 --> ULONG Füllwert (BYTE: 0-255, WORD: >255, LONG: >65535)
  1305. ;
  1306. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles in Ordnung
  1307. ;                          - FALSE, wenn Fehler (Info mit »LastError()«)
  1308. ;
  1309. ; Bemerkung:   Bei Wort- und Langwort-Modus wird die Größe auf das nächste
  1310. ;              Vielfache von 2 bzw. 4 abgerundet, um so eine Bereichsüber-
  1311. ;              schreitung zu vermeiden. Achten Sie darauf, daß der Bereich
  1312. ;              mindestens so groß ist, um einen Wert aufzunehmen, anderen-
  1313. ;              falls wird aufgrund der Abrundung keine Füllung durchgeführt.
  1314. ;              Diese Funktion löscht automatisch die Prozessor-Caches.
  1315. ;============================================================================
  1316.  
  1317. ;*** extra.library / GetMem()                (OFFSET -252) V1.323 ***
  1318. ;============================================================================
  1319. ; Diese Funktion belegt Speicher via »AllocMem()« der exec.library, bindet
  1320. ; aber zusätzlich sämtliche Bereiche in die Speicherliste der Task-Struktur
  1321. ; des aufrufenden Tasks ein. Somit wird verhindert, daß der Speicherplatz bis
  1322. ; zum nächsten Reset blockiert bleibt, wenn vergessen wurde, diesen wieder
  1323. ; freizugeben, bevor das Programm beendet wurde. In diesem Falle wird der be-
  1324. ; legte Speicherplatz automatisch wieder freigegeben, wenn der Task aus dem
  1325. ; System entfernt wird.
  1326. ;----------------------------------------------------------------------------
  1327. ; Synopsis:    address = GetMem (Size, Requirements)
  1328. ;                D0*              D0         D1
  1329. ;
  1330. ; Eingaben:    D0 --> ULONG die Größe des gewünschten Bereichs in Byte
  1331. ;              D1 --> ULONG die Eigenschaften des gewünschten Bereichs
  1332. ;
  1333. ; Ergebnis:    D0 --> APTR - auf die Adresse des belegten Bereichs
  1334. ;                          - 0-PTR, wenn die gewünschte Speicherart bzw.
  1335. ;                            Größe nicht verfügbar ist
  1336. ;
  1337. ; Bemerkung:   Der Wert MEMF_CLEAR zum Löschen des belegten Bereichs wird
  1338. ;              intern mit den Requirements verknüpft und braucht somit nicht
  1339. ;              explizit angegeben werden.
  1340. ;
  1341. ; Siehe auch:  »UnGetMem()«
  1342. ;============================================================================
  1343.  
  1344. ;*** extra.library / UnGetMem()              (OFFSET -258) V1.323 ***
  1345. ;============================================================================
  1346. ; Diese Funktion ist das Gegenstück zu »GetMem()«. Sie gibt entweder den an-
  1347. ; gegebenen Speicherblock oder alle Blöcke, welche mittels der o.g. Funktion
  1348. ; für den aufrufenden Task belegt wurden, wieder frei.
  1349. ;----------------------------------------------------------------------------
  1350. ; Synopsis:    VOID UnGetMem (Block)
  1351. ;                              A0
  1352. ;
  1353. ; Eingaben:    A0 --> APTR - die Adresse eines Speicherblocks von »GetMem()«
  1354. ;                          - ein 0-PTR gibt alle Speicherblöcke frei
  1355. ;
  1356. ; Siehe auch:  »GetMem()«
  1357. ;============================================================================
  1358.  
  1359. ;*** extra.library / OutlineOff()            (OFFSET -264) V1.323 ***
  1360. ;============================================================================
  1361. ; Diese Funktion schaltet den AreaOutline-Mode des angegebenen RastPorts aus.
  1362. ;----------------------------------------------------------------------------
  1363. ; Synopsis:    VOID OutlineOff (RastPort)
  1364. ;                                 A0!
  1365. ;
  1366. ; Eingaben:    A0 --> APTR auf eine gültige RastPort-Struktur
  1367. ;
  1368. ;   ACHTUNG:   In C/C++ ist die A0-APTR-Eingabe als Typ STRUCT RastPort*
  1369. ;   ¯¯¯¯¯¯¯¯   zu behandeln.
  1370. ;
  1371. ; Siehe auch:  »OutlineOn()«, »SetOPen()«
  1372. ;============================================================================
  1373.  
  1374. ;*** extra.library / OutlineOn()             (OFFSET -270) V1.323 ***
  1375. ;============================================================================
  1376. ; Diese Funktion schaltet den AreaOutline-Mode des angegebenen RastPorts ein.
  1377. ;----------------------------------------------------------------------------
  1378. ; Synopsis:    VOID OutlineOn (RastPort)
  1379. ;                                A0!
  1380. ;
  1381. ; Eingaben:    A0 --> APTR auf eine gültige RastPort-Struktur
  1382. ;
  1383. ;   ACHTUNG:   In C/C++ ist die A0-APTR-Eingabe als Typ STRUCT RastPort*
  1384. ;   ¯¯¯¯¯¯¯¯   zu behandeln.
  1385. ;
  1386. ; Siehe auch:  »OutlineOff()«, »SetOPen()«
  1387. ;============================================================================
  1388.  
  1389. ;*** extra.library / SetOPen()               (OFFSET -276) V1.323 ***
  1390. ;============================================================================
  1391. ; Diese Funktion setzt den für die Area-Outlines zu benutzenden Farbstift.
  1392. ;----------------------------------------------------------------------------
  1393. ; Synopsis:    VOID SetOPen (RastPort, Pen)
  1394. ;                              A0!     D0!
  1395. ;
  1396. ; Eingaben:    A0 --> APTR  auf eine gültige RastPort-Struktur
  1397. ;              D0 --> UBYTE Nummer des zu verwendenden Farbstiftes
  1398. ;
  1399. ;   ACHTUNG:   Diese Funktion schaltet den AreaOutline-Modus automatisch
  1400. ;   ¯¯¯¯¯¯¯¯   ein, wenn er noch nicht aktiv sein sollte !!
  1401. ;               In C/C++ ist die A0-APTR-Eingabe als Typ STRUCT RastPort*
  1402. ;              zu behandeln.
  1403. ;
  1404. ; Siehe auch:  »OutlineOff()«, »OutlineOn()«
  1405. ;============================================================================
  1406.  
  1407. ;*** extra.library / SpecText()              (OFFSET -282) V1.323 ***
  1408. ;============================================================================
  1409. ; Diese Funktion arbeitet wie »Text()« der graphics.library, nur wird hier
  1410. ; um den Text eine Umrandung gezeichnet, wodurch Sie bei entsprechender Farb-
  1411. ; wahl u.a. Schatten-, Outline- od. Reliefeffekte erzeugen können. Durch
  1412. ; Flags haben Sie auch die Möglichkeit z.B. die aktuellen Farben eines Rast-
  1413. ; ports zu verwenden, was es ermöglicht die Farben in höheren Programmier-
  1414. ; sprachen einfach durch Verwendung der COLOR-Befehle solcher Sprachen ein-
  1415. ; zustellen bzw. zu verändern. Ein weiterer Unterschied zu der Gfx-Funktion
  1416. ; ist der, daß sich die X/Y-Positionen hier auf die linke obere Ecke be-
  1417. ; ziehen, und nicht wie bei »Text()« auf die Baseline des verwendeten Fonts.
  1418. ;----------------------------------------------------------------------------
  1419. ; Synopsis:    success = SpecText (RastPort, String, xPos, yPos)
  1420. ;                D0*                 A0!      A1!    D0!    D1!
  1421. ;
  1422. ; Eingaben:    A0 --> APTR   auf eine gültige RastPort-Struktur
  1423. ;              A1 --> STRPTR auf den auszugebenden Text(+0)
  1424. ;              D0 --> UWORD  die X-Koordinate, wo der Text erscheinen soll
  1425. ;              D1 --> UWORD  die Y-Koordinate, wo der Text erscheinen soll
  1426. ;
  1427. ; Ergebnis:    D0 --> BOOL - TRUE , wenn alles funktioniert hat
  1428. ;                          - FALSE, wenn zu wenig Speicher für benötigte
  1429. ;                                   IntuiText-Strukturen
  1430. ;
  1431. ; Bemerkung:   Bevor Sie diese Funktion aufrufen sollten Sie mit der Funk-
  1432. ;              tion »SpecTextPrefs()« einstellen, wie diese Funktion arbei-
  1433. ;              ten soll. Wenn keine Einstellungen vorgenommen wurden, dann
  1434. ;              werden folgende Defaults benutzt: MPen=0, TLPen=2, BRPen=1,
  1435. ;              Style=STS_Plain, Maske=STM_Outline und Flags=STF_AP2MP. Die
  1436. ;              Einstellungen des angegebenen RastPorts werden durch diese
  1437. ;              Funktion NICHT verändert.
  1438. ;
  1439. ;   ACHTUNG:   Wenn der angegebene RastPort der eines Intuition-Windows ist,
  1440. ;   ¯¯¯¯¯¯¯¯   dann werden zu lange Texte am Rand autom. abgeschnitten. Han-
  1441. ;              delt es sich jedoch um einen selbst eingerichteten RastPort
  1442. ;              der nicht über einen Layer verfügt, dann haben Sie die Verant-
  1443. ;              wortung sicherzustellen, daß der Rand keinesfalls überschrie-
  1444. ;              ben wird (X/Y u. Textlänge beachten). Anderenfalls könnte es
  1445. ;              zu einem Systemabsturtz mit Datenverlust kommen, für den ich
  1446. ;              KEINERLEI HAFTUNG übernehme !!
  1447. ;               In C/C++ ist die A0-APTR-Eingabe als Typ STRUCT RastPort*
  1448. ;              zu behandeln.
  1449. ;
  1450. ; Siehe auch:  »SpecTextPrefs()«
  1451. ;============================================================================
  1452.  
  1453. ;*** extra.library / SpecTextPrefs()         (OFFSET -288) V1.323 ***
  1454. ;============================================================================
  1455. ; Mit dieser Funktion bestimmen Sie, wie die Funktion »SpecText()« dieser
  1456. ; Library arbeiten soll. Die Einstellungen gelten nur für den aufrufenden
  1457. ; Task, jeder Task kann also seine eigenen Prefs verwenden, ohne daß sie
  1458. ; sich gegenseitig in die Quere kommen. (möchte ja wohl auch sein, oder ??)
  1459. ;----------------------------------------------------------------------------
  1460. ; Synopsis:    VOID SpecTextPrefs (MPen, TLPen, BRPen, Style, Mask, Flags)
  1461. ;                                  D0!    D1!    D2!    D3!   D4!    D5!
  1462. ;
  1463. ; Eingaben:    D0 --> UBYTE Nr. der gewünschten Schriftfarbe (MainPen)
  1464. ;              D1 --> UBYTE Nr. der Farbe für ob./li.-Umrandung (TopLeftPen)
  1465. ;              D2 --> UBYTE Nr. der Farbe für un./re.-Ränder (BottomRightPen)
  1466. ;              D3 --> UBYTE der zu verwendende SoftStyle (s.extradefs.i)
  1467. ;              D4 --> UBYTE eine Maske, die angibt welche Umrandungsteile tat-
  1468. ;                           sächlich gezeichnet werden sollen (s. Bemerkung)
  1469. ;              D5 --> UWORD zusätzliche Spezifikationen (s. extradefs.i)
  1470. ;
  1471. ; Bemerkung:   Wenn die Flags »STF_AP2MP«, »STF_BP2TL« bzw. »STF_OP2BR« an-
  1472. ;              gegeben werden, dann werden die Parameter »MPen«, »TLPen« und
  1473. ;              »BRPen« deshalb NICHT ignoriert, vielmehr werden sie vermerkt
  1474. ;              und kommen zur Anwendung, wenn durch eine Änderung der Flags
  1475. ;              die o.g. Flags nicht mehr länger existent sind. In der Maske
  1476. ;              bedeutet jedes gesetzte Bit, daß der entsprechende Teil der
  1477. ;              Umrandung gezeichnet wird. Einige vordefinierte Werte finden
  1478. ;              Sie in dem Includefile »extradefs.i«
  1479. ;
  1480. ;              Die Maske hat folgendes Format:
  1481. ;              Bit-Nr. |  7 |  6 |  5 |  4 |  3 |  2 |  1 |  0 
  1482. ;              --------+----+----+----+----+----+----+----+----
  1483. ;              Randpos.| TL |  T | TR |  R | BR |  B | BL |  L
  1484. ;
  1485. ;              TL=oben/links,   T=oben,  TR=oben/rechts, R=rechts,
  1486. ;              BR=unten/rechts, B=unten, BL=unten/links, L=links
  1487. ;
  1488. ;   ACHTUNG:   Wenn Sie keine Flags zur Uebernahme von nur einzelnen Kompo-
  1489. ;   ¯¯¯¯¯¯¯¯   nenten verwenden, dann werden alle Werte übernommen.
  1490. ;
  1491. ; Siehe auch:  »SpecText()«
  1492. ;============================================================================
  1493.  
  1494. ;*** extra.library / ShowMsg()               (OFFSET -294) V1.323 ***
  1495. ;============================================================================
  1496. ; Diese Funktion stellt eine Alternative zu der Routine »DisplayAlert()« der
  1497. ; intuition.library dar. Diese Funktion arbeitet grundsätzlich genauso wie
  1498. ; die Intuition-Routine, bietet aber bei der Gestaltung des Alert-Textes noch
  1499. ; die Möglichkeit, Schriftfarbe und Schriftstil Ihren Wünschen entsprechend
  1500. ; zu wählen. Außerdem paßt sich diese Funktion ab OS 2.0 automatisch an die
  1501. ; aktuellen »overscan.prefs« an, und landet so nicht, wie ihrer großen Intu-
  1502. ; ition-Schwester schon öfter passiert, außerhalb der Bildröhre ?!
  1503. ;----------------------------------------------------------------------------
  1504. ; Synopsis:    button = ShowMsg (Param, Type, Height, ColorTab)
  1505. ;                D0*              A0!   D0!     D1       D2!
  1506. ;
  1507. ; Eingaben:    A0 --> STRPTR auf den Parameter-String (s. Bemerkung)
  1508. ;              D0 --> LONG   Alert-Typ, hiervon ist nur das MSB interessant:
  1509. ;                             MSB (Bit 31) gesetzt DeadEnd, sonst Recovery
  1510. ;                            Nach einem DeadEnd-Alert folgt ein System-Reset.
  1511. ;              D1 --> ULONG  die Höhe des Alerts in Videozeilen (max. 200)
  1512. ;              D2 --> APTR - auf eine optionale Farbtabelle (s. Bemerkung)
  1513. ;                          - 0-PTR zur Verwendung der Standardfarben
  1514. ;
  1515. ; Ergebnis:    D0 --> BOOL - UPPER, wenn linke Maustaste gedrückt
  1516. ;                          - EQUAL, wenn rechte Maustaste gedrückt
  1517. ;                          - LOWER, Fehler (genaue Info mit »LastError()«)
  1518. ;
  1519. ; Bemerkung:   Wenn Ihnen die Standardfarben nicht recht sind, dann können
  1520. ;              Sie sie durch die Angabe einer Farbtabelle folgenden Formats
  1521. ;              auf die von Ihnen gewünschten Werte ändern. Für alle Farben,
  1522. ;              für die kein Eintrag in der Tabelle existiert, werden weiter-
  1523. ;              hin die Standardfarben benutzt. Die Farbanteile können jeweils
  1524. ;              Werte von 0-15 annehmen. Assembler-Programmierer können zur
  1525. ;              einfacheren Erstellung der Tabelle das Macro »SMCOLOR()« aus
  1526. ;              dem Includefile »extradefs.i« verwenden.
  1527. ;               Für BASIC u. C/C++ sind hierfür ähnliche Funktionen bzw.
  1528. ;              Macros in den entsprechenden Includefiles definiert. Bitte
  1529. ;              entnehmen Sie die Beschreibung jener Macros bitte direkt aus
  1530. ;              den entsprechenden Includefiles.
  1531. ;
  1532. ;              Aufbau der Farbtabelle:
  1533. ;         +-->   UBYTE Nr. der Farbe (3-15)(0-2 werden ignoriert)
  1534. ;         |    + UWORD Rotanteil*256 + Grünanteil*16 + Blauanteil
  1535. ;         |    + UBYTE folgt ein weiterer Farbeintrag ?? (0=nein/1=ja)
  1536. ;         |
  1537. ;         |    wenn weiterer Farbeintrag=ja, dann --+
  1538. ;         |                                         |
  1539. ;         +-----------------------------------------+
  1540. ;
  1541. ;              Aufbau des Parameter-Stings:
  1542. ;         +-->   UWORD X-Koordinate dieses Teilstrings ----\ (jeweils bezogen
  1543. ;         |    + UBYTE Y-Koordinate dieses Teilstrings ----/ auf li./ob. Ecke)
  1544. ;         |    + UBYTE neue SpecTextPrefs ?? (0=nein/1=ja)
  1545. ;         |
  1546. ;         |    wenn SpecTextPrefs=ja, dann
  1547. ;         |      + UBYTE Nr. des für »SpecText()« zu verwendenden »MPen« \
  1548. ;         |      + UBYTE Nr. des zu verwendenden »TLPen«   ______________/
  1549. ;         |      + UBYTE Nr. des zu verwendenden »BRPen«  /    \  /
  1550. ;         |      + UBYTE der zu verwendende SoftStyle   _/      \/
  1551. ;         |      + UBYTE die zu verwendende Randmaske _/(s. »SpecTextPrefs()«)
  1552. ;         |    ansonsten folgt direkt
  1553. ;         |
  1554. ;         |    + TEXT  der auszugebende Text selbst mit abschließendem 0-Byte 
  1555. ;         |    + UBYTE folgt ein weiterer Teilstring ?? (0=nein/1=ja)
  1556. ;         |
  1557. ;         |    wenn weiterer Teilstring=ja, dann --+
  1558. ;         |                                        |
  1559. ;         +----------------------------------------+
  1560. ;
  1561. ;            - Zur einfacheren Erstellung des Parameter-Strings können
  1562. ;              Assembler-Programmierer die Macros »SMTEXTP()« u. »SMTEXT()«
  1563. ;              aus dem mitgelieferten Includefile »extradefs.i« verwenden.
  1564. ;               Für BASIC u. C/C++ sind hierfür ähnliche Funktionen bzw.
  1565. ;              Macros in den entsprechenden Includefiles definiert. Bitte
  1566. ;              entnehmen Sie die Beschreibung jener Macros bitte direkt aus
  1567. ;              den entsprechenden Includefiles.
  1568. ;
  1569. ;              Tabelle der vorhandenen Standardfarben:
  1570. ;               1 - hellgrau (nur für TLPen u. BRPen) 3 - rot(100%)
  1571. ;               4 - grün(100%)     5 - blau(100%)     6 - gelb(100%)
  1572. ;               7 - violett(100%)  8 - türkis(100%)   9 - weiß(100%)
  1573. ;              10 - weinrot       11 - orange        12 - pink
  1574. ;              13 - schilfgrün    14 - lila          15 - himmelblau
  1575. ;
  1576. ;              Die Farben 0-2 sind reserviert und werden automatisch in 3, 4
  1577. ;              bzw. 5 umgewandelt, falls sie angegeben werden. Nur für TLPen
  1578. ;              und BRPen ist zusätzlich auch Farbe 1 erlaubt. Als Styles und
  1579. ;              Masken gelten die gleichen, wie bei »SpecTextPrefs()«
  1580. ;
  1581. ;              Bis zum Auftauchen der ersten Prefs im Parameterstring werden
  1582. ;              folgende Defaults verwendet: MPen=7, alle anderen Einträge 0.
  1583. ;
  1584. ;              Die Erstellung des Textes erfolgt, wie Sie sicher schon er-
  1585. ;              raten haben, via »SpecText()« dieser Library. Allerdings wer-
  1586. ;              den die aktuellen Prefs Ihres Task zu genannter Funktion durch
  1587. ;              die hier angegebenen Prefs in keinster Weise verändert.
  1588. ;
  1589. ;   ACHTUNG:   Diese Funktion darf NUR von vollwertigen DOS-Prozessen auf-
  1590. ;   ¯¯¯¯¯¯¯¯   gerufen werden. Ein normaler EXEC-Task ist nicht ausreichend.
  1591. ;
  1592. ;              Nur OCS/ECS/AGA-Version:
  1593. ;              ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  1594. ;              Der von dieser Funktion benutzte RastPort hat KEINEN Layer,
  1595. ;              d.h. Sie müssen selbst aufpassen, daß die Texte innerhalb des
  1596. ;              RastPorts bleiben (640 x angegebene Höhe). Durch die Verwen-
  1597. ;              dung von 16 Farben benötigt diese Funktion gegenüber der In-
  1598. ;              tuition-Routine wesentlich mehr ChipRam (bei max. Höhe 64 KB).
  1599. ;              Sollte diese Menge nicht mehr verfügbar sein, so bricht diese
  1600. ;              Funktion mit einer entsprechenden Fehlermeldung ab.
  1601. ;
  1602. ;              Nur CGX-Version:
  1603. ;              ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  1604. ;              Bei der CGX-Version kann es vorkommen, das der Mauszeiger nach
  1605. ;              abschalten des Sprite-DMA (während der Anzeige der Message)
  1606. ;              weiterhin sichtbar bleibt. Das hängt davon ab, ob die GfxBase
  1607. ;              gültige SimpleSprite-Einträge für alle Hardware-Sprites hat.
  1608. ;              Wenn Sie grundsätzlich eine CGX-Workbench verwenden, und Ihr
  1609. ;              System hochfahren ohne vor Öffnung des WB-Screens irgendwelche
  1610. ;              Ausgaben durch die Startup-Sequenz zu tätigen, dann sind o.g.
  1611. ;              Einträge in der GfxBase immer uninitialisiert, und der Maus-
  1612. ;              zeiger bleibt demzufolge immer sichtbar. Um dies zu ändern, muß
  1613. ;              einfach mal ein normaler Amiga-Screen (PAL, NTSC, EURO36 etc.)
  1614. ;              geöffnet werden, was dazu führt, daß die Einträge initialisiert
  1615. ;              werden. Eine zweite Möglichkeit ist, einfach die ENV-Variable
  1616. ;              KEEPAMIGAVIDEO von CyberGraphX zu aktivieren.
  1617. ;
  1618. ; Siehe auch:  »SpecText()«, »SpecTextPrefs()«
  1619. ;============================================================================
  1620.  
  1621. ;*** extra.library / SMCOLOR() ***
  1622. ;============================================================================
  1623. ; Dieses Macro erstellt einen Farbeintrag für die optional anzugebende Farb-
  1624. ; tabelle für die Funktion »ShowMsg()«.
  1625. ;----------------------------------------------------------------------------
  1626. ; Definiert:   extradefs.i  (Copyright © 1998-2001 RhoSigma, Roland Heyder)
  1627. ;
  1628. ; Schablone:   Pen/A/N, Red/A/N, Green/A/N, Blue/A/N, END/K/S
  1629. ;
  1630. ; Parameter:   Pen   --> Nr. des zu ändernden Farbstiftes (3-15)
  1631. ;                             (0-2 sind reserviert u. werden ignoriert)
  1632. ;
  1633. ;              Red   --> Rot-Anteil der neuen Farbe (0-15)
  1634. ;              Green --> Grün-Anteil der neuen Farbe (0-15)
  1635. ;              Blue  --> Blau-Anteil der neuen Farbe (0-15)
  1636. ;
  1637. ;              END   --> Wird dieses Schlüsselwort angegeben, dann endet die
  1638. ;                        Farbtabelle an dieser Stelle, anderenfalls muß ein
  1639. ;                        weiterer Farbeintrag (Macro-Aufruf) folgen.
  1640. ;
  1641. ; Bemerkung:   Ein Beispiel für die Benutzung dieses Macros finden Sie in der
  1642. ;              Datei »demo/ShowMsgDemo.ASM«.
  1643. ;
  1644. ; Siehe auch:  »SMTEXTP()«, »SMTEXT()«, »ShowMsg()«
  1645. ;============================================================================
  1646.  
  1647. ;*** extra.library / SMTEXTP() ***
  1648. ;============================================================================
  1649. ; Dieses Macro erstellt einen Teilstring des Parameterstrings der Funktion
  1650. ; »ShowMsg()« inclusive der gewünschten Einstellungen für die Textausgabe.
  1651. ; Wahlweise kann der Text automatisch zentriert, oder links- bzw. rechtsbündig
  1652. ; ausgerichtet werden.
  1653. ;----------------------------------------------------------------------------
  1654. ; Definiert:   extradefs.i  (Copyright © 1998-2001 RhoSigma, Roland Heyder)
  1655. ;
  1656. ; Schablone:   xPos/A/N, yPos/A/N, MPen/A/N, TLPen/A/N, BRPen/A/N, Style/A/N,
  1657. ;              Mask/A/N, Text/A, END/K/S
  1658. ;
  1659. ; Parameter:   xPos  --> x-Position des Textes,
  1660. ;                             oder einer der oben definierten SMTPOS-Werte
  1661. ;
  1662. ;              yPos  --> y-Position des Textes,
  1663. ;                             Ausrichtung erfolgt an der Oberkante des Fonts
  1664. ;
  1665. ;              MPen  --> gewünschter MainPen        \
  1666. ;              TLPen --> gewünschter TopLeftPen     |
  1667. ;              BRPen --> gewünschter BottomRightPen | (s. »SpecTextPrefs()«)
  1668. ;              Style --> gewünschter SoftStyle      |
  1669. ;              Mask  --> gewünschte  Randmaske      /
  1670. ;
  1671. ;              Text  --> der auszugebende Text selbst,
  1672. ;                             in <..>, wenn Leerzeichen enthalten sind
  1673. ;
  1674. ;              END   --> Wird dieses Schlüsselwort angegeben, dann endet der
  1675. ;                        Parameterstring an dieser Stelle, anderenfalls muß
  1676. ;                        ein weiterer Teilstring (Macro-Aufruf) folgen.
  1677. ;
  1678. ; Bemerkung:   Dieses Macro sollten Sie nur dann verwenden, wenn Sie für
  1679. ;              diesen Teilstring neue Einstellungen für Farben etc. machen
  1680. ;              wollen. Wenn dieser Teilstring jedoch mit den gleichen Ein-
  1681. ;              stellungen ausgegeben werden soll, wie der vorhergehende bzw.
  1682. ;              Sie die Default-Einstellungen verwenden wollen, dann müssen
  1683. ;              Sie stattdessen das Macro »SMTEXT()« verwenden.
  1684. ;
  1685. ;              Ein Beispiel für die Benutzung dieses Macros finden Sie in der
  1686. ;              Datei »demo/ShowMsgDemo.ASM«.
  1687. ;
  1688. ; Siehe auch:  »SMCOLOR()«, »SMTEXT()«, »ShowMsg()«
  1689. ;============================================================================
  1690.  
  1691. ;*** extra.library / SMTEXT() ***
  1692. ;============================================================================
  1693. ; Dieses Macro erstellt einen Teilstring des Parameterstrings der Funktion
  1694. ; »ShowMsg()«. Wahlweise kann der Text automatisch zentriert, oder links- bzw.
  1695. ; rechtsbündig ausgerichtet werden.
  1696. ;----------------------------------------------------------------------------
  1697. ; Definiert:   extradefs.i  (Copyright © 1998-2001 RhoSigma, Roland Heyder)
  1698. ;
  1699. ; Schablone:   xPos/A/N, yPos/A/N, Text/A, END/K/S
  1700. ;
  1701. ; Parameter:   xPos  --> x-Position des Textes,
  1702. ;                             oder einer der oben definierten SMTPOS-Werte
  1703. ;
  1704. ;              yPos  --> y-Position des Textes,
  1705. ;                             Ausrichtung erfolgt an der Oberkante des Fonts
  1706. ;
  1707. ;              Text  --> der auszugebende Text selbst,
  1708. ;                             in <..>, wenn Leerzeichen enthalten sind
  1709. ;
  1710. ;              END   --> Wird dieses Schlüsselwort angegeben, dann endet der
  1711. ;                        Parameterstring an dieser Stelle, anderenfalls muß
  1712. ;                        ein weiterer Teilstring (Macro-Aufruf) folgen.
  1713. ;
  1714. ; Bemerkung:   Dieses Macro sollten Sie nur dann verwenden, wenn Sie für
  1715. ;              diesen Teilstring die gleichen Einstellungen wie für den vor-
  1716. ;              hergehenden Teilstring verwenden wollen. Wenn dieser Teil-
  1717. ;              string jedoch neue Einstellungen für Farben etc. erhalten
  1718. ;              soll, dann müssen Sie stattdessen das Macro »SMTEXTP()« ver-
  1719. ;              wenden.
  1720. ;
  1721. ;              Ein Beispiel für die Benutzung dieses Macros finden Sie in der
  1722. ;              Datei »demo/ShowMsgDemo.ASM«.
  1723. ;
  1724. ; Siehe auch:  »SMCOLOR()«, »SMTEXTP()«, »ShowMsg()«
  1725. ;============================================================================
  1726.  
  1727. ;*** lvo / Lib-Call-Macro ***
  1728. ;============================================================================
  1729. ; Dieses Macro dient zum Aufruf einer Funktion aus der dazugehörigen Library.
  1730. ;  Dabei ist dieses Macro gegenüber den CALL-Macros des NDK jedoch so intelli-
  1731. ; gent, daß es erkennt, ob mit ihm auch wirklich eine Funktion der zugehörigen
  1732. ; Library aufgerufen wird. Damit wird vermieden, daß versehendlich z.B. eine
  1733. ; Funktion der exec.library mit dem Macro (und damit natürlich auch dem Zeiger)
  1734. ; der graphics.library aufgerufen werden kann, was höchstwahrscheinlich sofort
  1735. ; einen Systemabsturz nach sich ziehen würde.
  1736. ;  Außerdem haben Optimal-Programmierer auch die Möglichkeit Quick-Aufrufe zu
  1737. ; verwenden, um jedes überflüssige Byte einzusparen. Für die Programmierung re-
  1738. ; entranter Programme ist ebenfalls eine Syntax definiert, bei der die voll-
  1739. ; ständige effektive Addresse des Basis-Zeigers als Parameter übergeben werden
  1740. ; muß, da dort ja keine flüchtigen absoluten Adressen verwendet werden dürfen.
  1741. ;----------------------------------------------------------------------------
  1742. ; Definiert:   ... _lib.i  (Copyright © 1998-2001 RhoSigma, Roland Heyder)
  1743. ;
  1744. ; Schablone:   Func/A, Opts/F/S
  1745. ;
  1746. ; Parameter:   Func --> Name der aufzurufenden Funktion ohne »_LVO_LIBNAME_«
  1747. ;
  1748. ;              Opts --> - das Schlüsselwort »OK« für einen QuickJump-Aufruf
  1749. ;                         (s. Bemerkung)
  1750. ;
  1751. ;                       - Opts weglassen, um Basis-Symbol »_LibnameBase« ins
  1752. ;                         Register A6 zu laden
  1753. ;
  1754. ;                       - die effektive Adresse, welche die Basis der Library
  1755. ;                         enthält (z.B. »globals_Libname(a5)«)
  1756. ;
  1757. ; Bemerkung:   Wird das Schlüsselwort »OK« angegeben, dann wird davon ausge-
  1758. ;              gangen, daß die richtige Basisadresse der Library bereits im
  1759. ;              Register A6 steht, und es wird sofort in die Funktion gesprungen.
  1760. ;============================================================================
  1761.